Errores y reintentos

Todos los errores (salvo los del endpoint de token, que siguen OAuth 2.0) llegan como application/problem+json (RFC 9457):

{
  "type": "urn:finora:cms-api:validacion",
  "title": "Datos inválidos",
  "status": 400,
  "codigo": "VALIDACION",
  "detail": "Uno o más campos no cumplen el esquema.",
  "instance": "/v1/cards/9b1f0e2d-3c4b-4a59-8e7f-6a5b4c3d2e10/limits",
  "requestId": "01JBX2Q7M8N9P0R1S2T3V4W5X6",
  "campos": [{ "campo": "maximoDiario", "motivo": "formato decimal con 2 decimales" }]
}

Campo	Uso
codigo	Decide por él. Es estable. La lista es abierta: tu código debe tolerar códigos nuevos (trátalos según su status)
type	urn:finora:cms-api:<codigo-en-kebab>
detail	Texto para personas; no lo analices
campos	En validaciones, el detalle por campo
requestId	Inclúyelo al pedir soporte
codigoRespuesta	En RECHAZO_LIBRO, el código ISO 8583 (DE 39) del rechazo
operacionPrevia	En RECARGA_DUPLICADA, la operación que ya usó la referencia
operacion	En OPERACION_NO_DISPONIBLE, la operación del contrato que falta

Catálogo

HTTP	codigo	Significado	¿Reintentar?
400	VALIDACION	Cuerpo o parámetros inválidos (también un campo JSON repetido, un parámetro no declarado o un número de tarjeta); campos detalla cada uno	No. Corrige
400	CURSOR_INVALIDO	Cursor alterado, de otro recurso o con otros filtros	No. Empieza sin after
400	RANGO_FECHAS_INVALIDO	Rango incoherente o de más de 93 días sin hasta	No. Corrige
400	VERSION_NO_SOPORTADA	X-Finora-Api-Version distinta de 1	No
400	MONTO_INVALIDO, ESCALA_INVALIDA	Importe ≤ 0, con signo o con una escala distinta de la de su unidad (Bs y USD 2, UVC 4). Nunca se redondea	No. Corrige
400	ACCION_INVALIDA	Acción de lote incoherente con su tipo	No
401	NO_AUTENTICADO, TOKEN_VENCIDO	Sin token válido o vencido	Sí, con un token nuevo
403	ALCANCE_INSUFICIENTE	Te falta el alcance de la operación	No. Pide el alcance
403	MTLS_REQUERIDO	La operación exige certificado de cliente (fase 2)	No
403	SIN_PERMISO	La operación solo la puede hacer quien hizo la solicitud	No
403	CUATRO_OJOS	Quien decide es quien pidió	No. Debe decidir otro
404	NO_ENCONTRADO	No existe o no pertenece a tus productos	No
405	METODO_NO_PERMITIDO	La ruta existe pero no admite el método; trae Allow	No
409	IDEMPOTENCIA_EN_CURSO	La misma clave sigue en curso o con resultado incierto	Sí, con la misma clave tras Retry-After
409	RECARGA_DUPLICADA	La referencia bancaria ya se usó en esa cuenta; trae operacionPrevia	No. Consulta la operación previa
409	CONFLICTO_VERSION	El recurso cambió desde que lo leíste	Relee y vuelve a decidir
409	ESTADO_NO_PERMITE	El estado actual no admite la acción (siempre 409)	No
409	CURSOR_CONCURRENTE	Otra confirmación de cursor ganó la carrera	Relee los eventos
409	SOLICITUD_PENDIENTE_EXISTE	Ya hay una solicitud pendiente para ese objeto	No. Espera su decisión o retírala
409	BLOQUEO_ADMINISTRATIVO, ES_PRINCIPAL, CAMBIO_DECIDIDO	Bloqueo de operador, vínculo principal o solicitud ya decidida	No
413	LOTE_DEMASIADO_GRANDE, CUERPO_DEMASIADO_GRANDE	Lote por encima de sus topes o cuerpo de más de 64 KB	No. Divide
415	TIPO_NO_SOPORTADO	El cuerpo no es application/json	No
422	IDEMPOTENCIA_CUERPO_DISTINTO	Misma Idempotency-Key con otro cuerpo	No. Usa otra clave
422	LIMITE_SUPERA_PRODUCTO, PRODUCTO_SIN_TOPES, VIGENCIA_NO_SOPORTADA, DISMINUCION_REQUIERE_AVISO	Reglas de los topes del plástico	No
422	LINEA_FUERA_DE_FICHA, REQUIERE_CLAUSULA, CAMBIO_REGIMEN_CON_SALDO, UNIDAD_NO_COINCIDE, LINEA_BAJO_PISO	Reglas de la línea de crédito	No
422	MOTIVO_NO_VIGENTE, SALDO_INSUFICIENTE, CUENTA_NO_OPERATIVA	Reglas del dinero prepago	No
422	RECHAZO_LIBRO	El libro rechazó la operación; trae codigoRespuesta (DE 39)	No con los mismos datos
422	CURSOR_ADELANTADO, REPLAY_FUERA_DE_VENTANA, URL_NO_PERMITIDA	Eventos y suscripciones	No
429	LIMITE_DE_TASA	Por encima de tu límite	Sí, tras Retry-After
500	ERROR_INTERNO	Fallo no previsto del gateway, sin detalle	Sí, con la misma clave y espera exponencial
501	OPERACION_NO_DISPONIBLE	La operación del contrato aún no está desplegada en la instalación; trae operacion	No. Llegará en una fase posterior
502	CMS_ERROR_INTERNO, CMS_RESPUESTA_INVALIDA, CMS_AUTENTICACION, RESPUESTA_CON_DATO_SENSIBLE	El CMS falló, respondió fuera de formato, rechazó la credencial del gateway o devolvió un dato sensible que no se entrega	Sí, con la misma clave: en una escritura el resultado es incierto (recibirás 409 hasta que venza la retención)
503	IDEMPOTENCIA_NO_DISPONIBLE, CMS_SATURADO, CMS_NO_DISPONIBLE, AUTENTICACION_NO_DISPONIBLE	El servicio no puede atender ahora; nada se ejecutó	Sí, con la misma clave, tras Retry-After

Hoy, 501 en las operaciones de negocio

Mientras el CMS de la instalación no publique una operación del contrato, el gateway responde 501 OPERACION_NO_DISPONIBLE en lugar de inventar una respuesta. Es el comportamiento esperado durante la fase Próximamente.

Política de reintento recomendada