Errores y motivos

Errores de la API

Los errores son RFC 9457 application/problem+json con un code estable:

Copiado

{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "The flow_id field is required.",
  "code": "validation_failed",
  "errors": { "flow_id": ["The flow_id field is required."] },
  "request_id": "01J..."
}

Decide según code, no según el texto. Indica el request_id cuando escribas a soporte.

`code`	HTTP	Significado
`unauthenticated`	401	Token ausente, inválido o caducado
`missing_ability`	403	Al token le falta el permiso necesario
`forbidden`	403	El propietario del token no puede hacerlo en el equipo
`not_found`	404	No existe en este equipo y modo
`team_required` / `team_not_found`	400 / 404	Envía la cabecera `X-Team-Id`, o no es un equipo del usuario
`validation_failed`	422	Mira `errors`
`flow_not_ready`	422	El flujo está archivado o incompleto (por ejemplo sin URL de privacidad)
`quota_exceeded`	402	Sin plan, prueba agotada, verificaciones incluidas agotadas con extras desactivados, o tope de extras alcanzado; `quota.reason` dice cuál
`not_cancellable` / `not_relinkable`	409	La sesión ya no está en un estado que lo permita
`idempotency_key_reused`	422	Se envió la misma `Idempotency-Key` con una petición distinta
`rate_limited`	429	Espera los segundos de `Retry-After`
`token_in_query`	400	Los tokens van solo en la cabecera `Authorization`

Motivos de decisión

Los reason_codes de un rechazo o de una petición de reenvío son valores estables. Trata los desconocidos como other.

Código	Significado
`doc_unreadable`	Las imágenes del documento están borrosas, cortadas o ilegibles
`doc_expired`	El documento está caducado o le queda poca validez
`doc_not_accepted`	Tipo o país de documento no admitido por el flujo
`doc_tampered_suspected`	Indicios de alteración
`selfie_mismatch`	El selfie no se parece a la persona del documento
`selfie_unclear`	El selfie es oscuro, borroso, está tapado o aparecen varias personas
`liveness_challenge_failed`	El vídeo no muestra el reto pedido
`liveness_screen_replay_suspected`	El vídeo parece la grabación de una pantalla o una foto
`poa_name_mismatch`	El nombre del justificante no coincide con el del documento
`poa_too_old`	El justificante es más antiguo de lo permitido
`poa_unreadable`	El justificante es ilegible
`under_age`	Menor de la edad mínima del flujo
`duplicate_suspected`	El mismo documento se usó en otra sesión de tu cuenta
`other`	Otro motivo

El solicitante ve un texto amable para cada código, nunca la redacción interna.