Errores y códigos de estado
Esta página es la referencia consolidada de los sobres de respuesta que utiliza cada ruta de la API del dominio de préstamos. La documentación de cada ruta enumera los códigos de estado que emite esa ruta concreta; esta página documenta la forma de cada sobre y el catálogo de valores de code con nombre que puede recibir.
Léala una vez antes de integrar; vuelva a ella cada vez que un estado distinto de 2xx le sorprenda.
Catálogo de códigos de estado
| Estado | Cuándo aparece | Ruta de ejemplo |
|---|---|---|
200 OK | Lectura correcta, reproducción idempotente, cancelación lógica, lote masivo procesado, transición de estado. | Todas las rutas que no son de creación. |
201 Created | Primera creación correcta en una ruta de registro único. | POST /borrowers. |
202 Accepted | Importación asíncrona iniciada — el trabajo continúa en segundo plano. | POST /imports. |
204 No Content | Actualmente ninguna ruta del dominio de préstamos lo devuelve. | — |
400 Bad Request | Fallo de validación de la solicitud: JSON mal formado, consulta mal formada, infracción del esquema. | Todas las rutas de modificación. |
401 Unauthorized | Sin encabezado Authorization, token desconocido o token revocado. | Todas las rutas. |
403 Forbidden | El llamante es una cuenta de inversor; los inversores no pueden usar la API de datos de monitorización (MONITORING_INVESTOR_FORBIDDEN). Un ?unmask=true por parte de un no administrador no devuelve 403: devuelve 200 con la PII enmascarada. | Todas las rutas. |
404 Not Found | El recurso no existe o pertenece a otra organización. | Todas las rutas que hacen referencia a un recurso. |
409 Conflict | Ya existe una fila activa con este id, se reutilizó una Idempotency-Key para una transición de estado distinta o la fase de confirmación no pudo ver el archivo cargado. | POST /borrowers, PATCH /loans/.../status, POST /imports/{id}/commit. |
413 Payload Too Large | Un lote de NDJSON masivo supera el límite de filas o de bytes. | POST /bulk/{entity}. |
422 Unprocessable Entity | Una fila referenciada no existe como activa en la misma cartera (REFERENCED_ENTITY_NOT_FOUND), o la transición de estado solicitada no está en la matriz de transiciones (INVALID_STATUS_TRANSITION). Los fallos de validación usan 400. | POST /loans, POST /payments, PATCH /loans/{loanRef}/status. |
429 Too Many Requests | Límite de frecuencia superado. La plataforma aplica límites de frecuencia por organización; el encabezado de respuesta Retry-After indica los segundos. | Todas las rutas. |
500 Internal Server Error | Error no controlado de la plataforma. Trátelo como transitorio; se puede reintentar con seguridad con la misma Idempotency-Key. | Todas las rutas. |
Trate cualquier 4xx distinto de 429 como un defecto de la solicitud — la lógica de su cliente debe rechazar la entrada en lugar de reintentar. Trate 429 y 500 como transitorios y reintente con espera progresiva; una Idempotency-Key hace que el reintento sea seguro.
Sobres estándar
La API del dominio de préstamos utiliza tres sobres de respuesta para los códigos de estado que no indican éxito. La forma del sobre le indica qué tipo de fallo está viendo.
Sobre de validación — 400 Bad Request
Se usa para infracciones del esquema, parámetros de consulta mal formados y rutas mal formadas.
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}| Campo | Tipo | Notas |
|---|---|---|
error | cadena | Resumen breve legible por humanos. |
fieldErrors[].path | cadena | Ruta con puntos del campo problemático. (root) indica el propio cuerpo, p. ej. cuando falló el análisis del JSON. |
fieldErrors[].message | cadena | Explicación legible por humanos. |
Algunas rutas emiten errors[] en lugar de fieldErrors[] para los fallos en parámetros de consulta (la convención del framework varía según la superficie). La forma path/message es idéntica; trate ambos nombres de array como intercambiables a efectos de análisis.
Sobre con código con nombre — 4xx
Se usa cuando el fallo tiene una causa específica que la plataforma nombra con un valor de code estable. La presencia de fieldErrors es opcional y depende de si el fallo puede atribuirse a un campo concreto.
{
"error": "a borrower with this id already exists",
"code": "ID_CONFLICT",
"fieldErrors": [
{ "path": "id", "message": "a borrower with this id already exists" }
]
}| Campo | Tipo | Notas |
|---|---|---|
error | cadena | Resumen legible por humanos. |
code | cadena | Código estable legible por máquina; consulte el glosario. |
fieldErrors[] | array | ausente | Presente cuando el fallo apunta a un campo concreto. |
Algunos sobres incluyen contexto estructurado adicional — por ejemplo, batch_too_large incluye un bloque fieldErrors que nombra el límite superado. La documentación de cada ruta los nombra.
Sobre de error simple — 404 / 401
Se usa para respuestas escuetas en las que ningún contexto adicional ayudaría al llamante. 404 es el ejemplo típico:
{ "error": "Not found" }Algunas rutas devuelven { "error": "...", "code": "NOT_FOUND" }; trate la presencia o ausencia de code en un 404 como informativa, no como algo de lo que dependa su lógica.
Dos espacios de códigos: mayúsculas frente a minúsculas
La API del dominio de préstamos utiliza dos espacios de nombres de code distintos, separados intencionadamente según la modalidad de ingesta:
- Las rutas de registro único (los POST, los PATCH, la cancelación y los GET de conciliación) emiten valores de código en
UPPER_CASE:ID_CONFLICT,PORTFOLIO_NOT_FOUND,REFERENCED_ENTITY_NOT_FOUND,INVALID_STATUS_TRANSITION,CHECK_VIOLATION,NOT_FOUND,UNKNOWN_KIND,COMMIT_FAILED,IDEMPOTENCY_CONFLICT,IDEMPOTENCY_KEY_REUSED,MONITORING_INVESTOR_FORBIDDEN. Las rutas de NDJSON masivo también devuelvenMONITORING_INVESTOR_FORBIDDENen mayúsculas. - Las rutas de NDJSON masivo emiten valores de código en
lower_case:batch_too_large,portfolio_not_found,portfolio_id_required,invalid_body,invalid_json, además de los códigos por fila documentados más abajo.
Cuando ramifique según code en su cliente, respete exactamente las mayúsculas y minúsculas. Los dos espacios de códigos son estables por separado; no los normalice.
Glosario de códigos de error
La plataforma asigna un code estable a cada modo de fallo con nombre. Úselos para la ramificación programática; el texto del mensaje error puede cambiar.
Espacio de códigos de registro único
| Código | Estado | Emitido por | Desencadenante |
|---|---|---|---|
ID_CONFLICT | 409 | POST /borrowers, POST /loans, POST /payments. | Ya existe una fila activa con el mismo id. |
PORTFOLIO_NOT_FOUND | 404 | Todas las rutas de escritura de registro único. | El portfolioId del cuerpo no existe en su organización. |
REFERENCED_ENTITY_NOT_FOUND | 422 | POST /loans, POST /payments. | borrowerId o loanId hace referencia a una fila que no existe como activa en la misma cartera. |
INVALID_STATUS_TRANSITION | 422 | PATCH /loans/{loanRef}/status. | El par de estados origen/destino no está en la matriz de transiciones. |
IDEMPOTENCY_CONFLICT | 409 | PATCH /loans/{loanRef}/status. | La Idempotency-Key ya se usó para una transición de estado distinta. Envíe la nueva transición con una clave nueva. |
IDEMPOTENCY_KEY_REUSED | 409 | POST /imports. | La Idempotency-Key ya se usó para una importación con parámetros de solicitud distintos (kind, filename, sizeBytes, …). La respuesta incluye importId y mismatchedFields. Envíe la nueva importación con una clave nueva. |
MONITORING_INVESTOR_FORBIDDEN | 403 | Todas las rutas de préstamos de monitorización, incluidas las de NDJSON masivo. | El llamante es una cuenta de inversor; los inversores no pueden usar la API de datos de monitorización. |
CHECK_VIOLATION | 400 | POST /payments. | Falló una regla de datos (normalmente la invariante de condonación; la capa de esquema rechaza la misma forma en el momento de la validación). |
NOT_FOUND | 404 | GET /borrowers/{id}, GET /payments/{id}, PATCH /loans/.../status, POST /payments/{id}/cancel, GET /loans/{externalId}. | La fila buscada no existe como activa en el ámbito indicado, o pertenece a otra organización. |
UNKNOWN_KIND | 400 | POST /imports. | kind no es uno de los seis tipos de préstamo. La respuesta incluye un array allowed. |
COMMIT_FAILED | 409 | POST /imports/{id}/commit. | La plataforma no encontró el archivo cargado; normalmente la carga nunca terminó. Reintente la carga y vuelva a confirmar. |
Espacio de códigos de NDJSON masivo
| Código | Estado | Desencadenante |
|---|---|---|
batch_too_large | 413 | El cuerpo supera las 10 000 filas o los 10 MB. error y fieldErrors[].message distinguen entre el límite de filas y el de bytes. |
portfolio_id_required | 400 | Falta ?portfolioId=<UUID> o no es un UUID válido. |
portfolio_not_found | 404 | El ?portfolioId= no existe como cartera activa en su organización. |
invalid_body | 400 | El cuerpo de la solicitud no pudo leerse como texto. |
invalid_json | (por fila) | Una fila no es JSON válido. Aparece dentro del array errors[] por fila; el lote devuelve 200. |
Un código que no figura en este glosario indica que la plataforma añadió un nuevo código con nombre desde la última revisión de esta página. Registre siempre el valor de code tal cual junto con el error de su aplicación para que el equipo de ingeniería pueda correlacionarlo.
Códigos de error por fila (masivo e importaciones asíncronas)
Tanto NDJSON masivo como las importaciones asíncronas devuelven errores por fila. La superficie masiva usa un conjunto de valores; la superficie de importaciones asíncronas usa un conjunto similar pero ligeramente diferente (en particular, incluye validation_error en lugar de validation_failed, lo que refleja una superficie más antigua). Las entradas por fila describen fallos de filas individuales dentro de un lote correcto, no fallos del sobre.
Códigos por fila de NDJSON masivo
| Código por fila | Desencadenante |
|---|---|
validation_failed | La fila no superó la validación del esquema. El campo message contiene los errores de validación. |
fk_violation | Una referencia de clave foránea de la fila (p. ej., borrowerId, loanId) no corresponde a una fila activa en la misma cartera. |
unique_violation | Ya existe una fila activa con el mismo (portfolio, externalId) o id. (No hay un código por fila id_conflict separado; ambos tipos de colisión de ID de llamante aparecen aquí.) |
check_violation | Falló una regla de datos — normalmente la regla de condonación de un pago. |
db_error | Un error inesperado al almacenar esta fila. La fila se notifica como fallida; el lote continúa. |
invalid_json | La fila no era JSON válido. La plataforma procesa el resto del lote. |
Códigos por fila de importaciones asíncronas
| Código por fila | Desencadenante |
|---|---|
parse_error | La línea no era JSON válido. |
validation_error | La fila no superó la validación del esquema. |
portfolio_mismatch | El portfolioId de la fila no coincide con la cartera de anclaje de la importación. |
processor_error | Un fallo inesperado del manejador durante el procesamiento de esta fila. |
Los errores al almacenar una fila (una referencia inexistente, un duplicado, una regla de datos incumplida) aparecen con uno de los códigos anteriores y el detalle en errorMessage.
Los errores por fila nunca se trasladan a una respuesta de nivel superior distinta de 200 en la superficie masiva — el lote en su conjunto es correcto si la propia solicitud estaba bien formada; los códigos por fila le indican qué se registró.
Semántica de reintentos
Un patrón de reintento seguro para cualquier ruta de modificación es:
- Genere una
Idempotency-Keydeterminista por operación lógica. Un UUIDv4 más un discriminador de ruta funciona. - Envíe la solicitud con la clave.
- Ante cualquiera de
2xx,409 ID_CONFLICT,409 IDEMPOTENCY_CONFLICT,409 IDEMPOTENCY_KEY_REUSED,404,403,400,413o422— no reintente. El resultado es definitivo. - Ante
429— reintente tras el tiempo indicado en el encabezadoRetry-After. - Ante
500o un error de red — reintente un número fijo y reducido de veces con espera exponencial. LaIdempotency-Keyhace que el reintento sea seguro tanto si el primer intento llegó como si no.
Un reintento de una solicitud correcta con la misma Idempotency-Key devuelve la misma respuesta que la original, con reused: true en la entidad afectada. Esta es la recuperación canónica del caso feliz tras un corte de red.
Lo que la plataforma nunca devuelve
Para la depuración operativa, es útil conocer lo que no ocurre:
- La plataforma no trata ningún código de estado
5xxcomo una funcionalidad. Un500es siempre un error que hay que corregir; nunca escriba lógica de cliente que dependa de una forma concreta de500. - Ninguna respuesta
404revela información de inquilinos. Un404sobre una fila que existe en otra organización es idéntico a un404sobre una fila que no existe en ninguna parte. No escriba lógica de cliente que deduzca la existencia entre inquilinos. - Ninguna respuesta correcta lleva un campo de cuerpo llamado
success: false. El código de estado es la fuente de verdad sobre si la llamada se completó correctamente; la forma del cuerpo aporta el detalle. - Ninguna ruta de escritura devuelve su propio UUID al estilo de un parámetro de ruta (encabezado "Location"). El UUID creado aparece en el campo
iddel cuerpo de la respuesta.