Catálogo de errores (Problems)

Todo error llega como application/problem+json (RFC 9457), con type, title, status, retryable y, cuando está presente, correlation_id.

Para la validación, descargue el esquema de Problem y el contrato OpenAPI v1 exactos.

Identificadores type de Problem

El type es un URI completo bajo https://fingertrackid.dev/problems/, por ejemplo https://fingertrackid.dev/problems/rate-limited.

• Es un identificador estable. No lo consulte en tiempo de ejecución ni trate como un problema que esa consulta falle. Compare la cadena type completa.
• Esta página es la documentación de todos los tipos. Cada uno tiene su propia sección más abajo, en https://docs.fingertrackid.com/api/errors/#<suffix> (por ejemplo #rate-limited), y abrir un URI de type en un navegador redirige a esa sección.
• Escriba su código en función de type y status. El title es texto legible para personas; solo es fijo para authentication-failed (Autenticação falhou, en portugués, como define el contrato) y assessment-result-expired (Assessment result expired). No condicione su lógica a title.
• El contrato permite errors[] (con pointer y code) solo en validation-failed, como campo opcional. No dependa de él para encontrar el campo incorrecto.

Resumen

Sufijo de type	HTTP	retryable	Rutas
validation-failed	400	false	Evaluación, feedback
event-context-invalid	400	false	Evaluación
occurred-at-out-of-window	400	false	Evaluación
authentication-failed	401	false	Evaluación, feedback
timestamp-out-of-window	401	true	Evaluación, feedback
request-replayed	401	true	Evaluación, feedback
forbidden	403	false	Evaluación, feedback
not-found	404	false	Feedback
idempotency-conflict	409	false	Evaluación, feedback
binding-conflict	409	false	Evaluación, feedback
assessment-result-expired	410	false	Evaluación
payload-too-large	413	false	Evaluación, feedback
unsupported-media-type	415	false	Evaluación, feedback
rate-limited	429	true	Evaluación, feedback
internal	500	false	Evaluación, feedback
assessment-unavailable	503	true	Evaluación, feedback

Las rutas de feedback tienen su propio catálogo cerrado de Problems en el OpenAPI de feedback, con títulos en inglés. El endpoint de captura del Web SDK usa algunos tipos más, enumerados en vistos en el navegador, y los tipos que la API no envía se enumeran después de ellos.

Tipos de evaluación y de feedback

validation-failed

400, no reintentable. La solicitud no se ajusta al esquema, o la ruta es una variación de /v1/assessments (cadena de consulta, barra final, método distinto de POST), o la solicitud lleva Expect/Trailer o un encabezado de framing duplicado. Corrija la solicitud según el esquema.

En una solicitud v1.1, esto incluye un tag fuera de la gramática (mayúsculas, guion, espacio, más de 64 caracteres, 11 o más dígitos en total) y un campo exclusivo de v1 (journey, action, journey_context). No hay un tipo de Problem aparte para la etiqueta.

400 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/validation-failed",
  "title": "Request inválido",
  "status": 400,
  "correlation_id": "corr-problem-validation-0001",
  "retryable": false,
  "errors": [
    {
      "pointer": "/journey",
      "code": "INVALID_ENUM"
    }
  ]
}

event-context-invalid

400, no reintentable. El event_context_token está presente, pero es inválido, caducó, ya se usó o pertenece a otro ámbito. No se almacena nada. En el perfil de producción gestionado, un token caduca a más tardar cuando se cumple la ventana de evidencia de su aplicación (60 o 300 segundos) desde que la captura de ese token llegó a FingerTrackID (la ventana de evidencia). No reintente: el mismo cuerpo recibe la misma respuesta, y un cuerpo distinto con los mismos IDs de operación es un idempotency-conflict. Para evaluar el evento de todos modos, envíelo una vez como una operación nueva (nuevos external_event_id e idempotency_key) con event_context_token: null. Cuando el navegador no tenga token, envíe null desde el principio (guía de integración).

400 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/event-context-invalid",
  "title": "Contexto do evento inválido",
  "status": 400,
  "correlation_id": "corr-problem-context-invalid-0001",
  "retryable": false
}

occurred-at-out-of-window

400, no reintentable. El occurred_at de una operación nueva está fuera de ±300 s respecto del reloj del servidor. Revise el reloj y el origen de la marca de tiempo; esta ruta no sirve para cargas retroactivas.

400 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/occurred-at-out-of-window",
  "title": "Evento fora da janela online",
  "status": 400,
  "correlation_id": "corr-problem-occurred-at-0001",
  "retryable": false
}

authentication-failed

401, no reintentable. Es el fallo de autenticación uniforme (vea autenticación): bytes, encabezados, key_id o decodificación del secreto incorrectos, o una credencial revocada, suspendida o bloqueada. Trátelo como un error de configuración y genere una alerta.

401 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/authentication-failed",
  "title": "Autenticação falhou",
  "status": 401,
  "correlation_id": "corr-problem-authentication-0001",
  "retryable": false
}

timestamp-out-of-window

401, reintentable. Su reloj está fuera de ±300 s respecto del reloj del servidor. Sincronícelo y envíe un nuevo intento.

401 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/timestamp-out-of-window",
  "title": "Timestamp da assinatura fora da janela",
  "status": 401,
  "correlation_id": "corr-problem-timestamp-0001",
  "retryable": true
}

request-replayed

401, reintentable. Se reutilizó un request_id. Envíe un nuevo intento y corrija el generador de IDs.

401 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/request-replayed",
  "title": "Identificador da tentativa já consumido",
  "status": 401,
  "correlation_id": "corr-problem-replay-0001",
  "retryable": true
}

forbidden

403, no reintentable. La credencial es válida, pero no tiene la capacidad de la ruta. Cree en la consola una credencial de servidor con ese permiso.

403 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/forbidden",
  "title": "Capability de assessment ausente",
  "status": 403,
  "correlation_id": "corr-problem-forbidden-0001",
  "retryable": false
}

not-found

404, no reintentable, solo en las rutas de feedback. La evaluación de destino no existe o está fuera del ámbito autenticado; ambos casos comparten esta respuesta. Revise el assessment_id en la ruta de la URL.

idempotency-conflict

409, no reintentable. La clave de idempotencia o el ID externo se reutilizó con contenido distinto. Concilie; no invente IDs nuevos automáticamente.

El tag es contenido: un reintento con los mismos IDs y otra etiqueta es un conflicto. También lo es un ID de una operación v1 enviado de nuevo en un cuerpo v1.1, o al revés: las operaciones v1 y v1.1 nunca comparten IDs.

409 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/idempotency-conflict",
  "title": "Chave de idempotência já usada com outro conteúdo",
  "status": 409,
  "correlation_id": "corr-problem-idempotency-0001",
  "retryable": false
}

binding-conflict

409, no reintentable. Las referencias de persona, cuenta o sesión son incompatibles con vínculos ya almacenados. En la ruta de evaluación, la causa habitual es un account_ref que ya está vinculado a otro subject_ref: una cuenta nunca cambia de persona. No se almacena ningún evento ni evaluación, y el mismo cuerpo recibe la misma respuesta, así que no lo reintente. Corrija el mapeo en su backend (mantenga sin cambios a lo largo del tiempo la clave y el prefijo de cada referencia, vea referencias de persona y de cuenta) y continúe su flujo normal: en un inicio de sesión, el inicio de sesión sigue adelante.

409 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/binding-conflict",
  "title": "Vínculo de identidade ou sessão incompatível",
  "status": 409,
  "correlation_id": "corr-problem-binding-conflict-0001",
  "retryable": false
}

assessment-result-expired

410, no reintentable, solo en la ruta de evaluación. La operación lógica autenticada existe, pero su resultado está fuera de la ventana de historial aprobada. Deje de reintentar; no cree IDs nuevos para regenerar la operación antigua.

410 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/assessment-result-expired",
  "title": "Assessment result expired",
  "status": 410,
  "retryable": false
}

payload-too-large

413, no reintentable. El cuerpo supera los 16384 bytes. Redúzcalo y vuelva a firmarlo.

413 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/payload-too-large",
  "title": "Payload excede o limite",
  "status": 413,
  "correlation_id": "corr-problem-payload-0001",
  "retryable": false
}

unsupported-media-type

415, no reintentable. Content-Type no es exactamente application/json, o Content-Encoding está presente.

415 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/unsupported-media-type",
  "title": "Representação do request não suportada",
  "status": 415,
  "correlation_id": "corr-problem-media-type-0001",
  "retryable": false
}

rate-limited

429, reintentable. Se superó la tasa de su cliente de servidor. Espere lo indicado en Retry-After y luego envíe un nuevo intento con el mismo cuerpo (límites).

429 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/rate-limited",
  "title": "Limite de assessments atingido",
  "status": 429,
  "correlation_id": "corr-problem-rate-limit-0001",
  "retryable": true
}

internal

500, no reintentable. Un fallo interno conocido antes de que se almacenara nada. No reintente automáticamente; abra una solicitud de soporte con el correlation_id.

500 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/internal",
  "title": "Falha interna não retentável",
  "status": 500,
  "correlation_id": "corr-problem-internal-0001",
  "retryable": false
}

assessment-unavailable

503, reintentable. Indisponibilidad o estado desconocido. Espere lo indicado en Retry-After (hoy siempre 1 segundo; espere al menos 1 segundo si alguna vez falta el encabezado) y luego envíe un nuevo intento con el mismo cuerpo: un request_id nuevo, marca de tiempo actual y firma nueva, porque el request_id del intento respondido puede ya estar consumido. Una evaluación retenida devuelve 200; un resultado caducado devuelve un 410 definitivo. Reintente un número acotado de veces dentro de su plazo de negocio, nunca en bucle.

503 · application/problem+json

{
  "type": "https://fingertrackid.dev/problems/assessment-unavailable",
  "title": "Assessment temporariamente indisponível",
  "status": 503,
  "detail": "Repita a mesma operação lógica com novo request_id; o commit pode ter ocorrido.",
  "correlation_id": "corr-assessment-timeout-0001",
  "retryable": true
}

Vistos en el navegador (Web SDK)

El Web SDK se comunica con su dominio de captura y gestiona él mismo estas respuestas, devolviendo a su código un estado como UNAVAILABLE. Usted nunca las analiza, pero pueden aparecer en el panel de red del navegador.

Sufijo de type	HTTP	Significado
origin-not-allowed	403	El origen de la página no es uno de los orígenes permitidos de la aplicación en este dominio de captura. La respuesta no lleva aprobación CORS, por lo que el navegador la oculta y el SDK informa TRANSPORT_ERROR
sdk-session-conflict	409	Un conflicto con el estado actual de la sesión del SDK; el SDK lo gestiona
event-context-conflict	409	Una solicitud de contexto del evento en conflicto para el mismo evento del SDK; el SDK la gestiona
sdk-unavailable	503	La captura no está disponible temporalmente; continúe con un contexto null

El endpoint de captura también usa validation-failed, authentication-failed, not-found, idempotency-conflict, payload-too-large, unsupported-media-type, rate-limited e internal con el mismo significado que arriba; allí, el SDK trata internal como reintentable.

Tipos que la API no envía

El catálogo de FingerTrackID reserva algunos tipos más. Un URI de type con uno de estos sufijos también lleva a esta página, pero las rutas de evaluación, feedback y captura nunca los devuelven: el código que gestiona los tipos anteriores gestiona todas las respuestas.

Sufijo de type	Lo que recibe en su lugar
signature-invalid, unknown-client, client-suspended	authentication-failed. Los fallos de autenticación son uniformes, así que un rechazo nunca le indica a quien llama si lo incorrecto era la firma, la clave o el estado de la credencial
nonce-replayed	request-replayed
external-event-conflict	idempotency-conflict
assessment-timeout, assessment-state-unknown	assessment-unavailable: un plazo agotado o un estado que no se pudo confirmar se reintenta con el mismo cuerpo
journey-key-cardinality-exceeded, assessment-profile-not-activated	Nada: están reservados para un perfil de solicitud futuro que hoy no se acepta. Las solicitudes v1 y v1.1 nunca los devuelven

401, 403, 429 y 503 en una frase cada uno

• 401 — falló la autenticación del intento. authentication-failed es uniforme y no se reintenta; timestamp-out-of-window y request-replayed se reintentan con un nuevo intento.
• 403 — usted está autenticado, pero la credencial no tiene la capacidad de la ruta.
• 429 — se superó la tasa del cliente de servidor. Espere lo indicado en Retry-After y luego reintente con un request_id, una marca de tiempo y una firma nuevos; reintentar sin esperar puede bloquear la credencial durante 10 minutos (límites).
• 503 — indisponibilidad o estado desconocido. Espere lo indicado en Retry-After y luego reintente con el mismo cuerpo y un request_id, una marca de tiempo y una firma nuevos, un número acotado de veces; una evaluación retenida devuelve 200; un resultado caducado devuelve un 410 definitivo.

Encabezados útiles

• En la API de servidor a servidor (evaluación y feedback), 429 y 503 llevan Retry-After en segundos enteros, como mínimo 1; hoy siempre envían 1. Lea el encabezado en lugar de fijar un valor en el código, y espere al menos 1 segundo si alguna vez falta. El 429 del endpoint de captura calcula su valor: por la tasa de sesiones nuevas, el tiempo hasta que quepa la próxima apertura de sesión; por el límite de sesiones concurrentes de la aplicación, hasta 1800 segundos. El Web SDK lo respeta por usted.
• Toda respuesta lleva X-Correlation-Id, opaco y sin datos personales. Consérvelo para soporte.
• Un POST a una ruta que no empieza por /v1/assessments recibe 404. Las variaciones de /v1/assessments (cadena de consulta, barra final) y cualquier método distinto de POST reciben 400 validation-failed.