Waafir
Esta página es una traducción automática pendiente de revisión humana. Puede contener errores.

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

EstadoCuándo apareceRuta de ejemplo
200 OKLectura 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 CreatedPrimera creación correcta en una ruta de registro único.POST /borrowers.
202 AcceptedImportación asíncrona iniciada — el trabajo continúa en segundo plano.POST /imports.
204 No ContentActualmente ninguna ruta del dominio de préstamos lo devuelve.—
400 Bad RequestFallo de validación de la solicitud: JSON mal formado, consulta mal formada, infracción del esquema.Todas las rutas de modificación.
401 UnauthorizedSin encabezado Authorization, token desconocido o token revocado.Todas las rutas.
403 ForbiddenEl 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 FoundEl recurso no existe o pertenece a otra organización.Todas las rutas que hacen referencia a un recurso.
409 ConflictYa 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 LargeUn lote de NDJSON masivo supera el límite de filas o de bytes.POST /bulk/{entity}.
422 Unprocessable EntityUna 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 RequestsLí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 ErrorError 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" }
  ]
}
CampoTipoNotas
errorcadenaResumen breve legible por humanos.
fieldErrors[].pathcadenaRuta con puntos del campo problemático. (root) indica el propio cuerpo, p. ej. cuando falló el análisis del JSON.
fieldErrors[].messagecadenaExplicació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" }
  ]
}
CampoTipoNotas
errorcadenaResumen legible por humanos.
codecadenaCódigo estable legible por máquina; consulte el glosario.
fieldErrors[]array | ausentePresente 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 devuelven MONITORING_INVESTOR_FORBIDDEN en 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ódigoEstadoEmitido porDesencadenante
ID_CONFLICT409POST /borrowers, POST /loans, POST /payments.Ya existe una fila activa con el mismo id.
PORTFOLIO_NOT_FOUND404Todas las rutas de escritura de registro único.El portfolioId del cuerpo no existe en su organización.
REFERENCED_ENTITY_NOT_FOUND422POST /loans, POST /payments.borrowerId o loanId hace referencia a una fila que no existe como activa en la misma cartera.
INVALID_STATUS_TRANSITION422PATCH /loans/{loanRef}/status.El par de estados origen/destino no está en la matriz de transiciones.
IDEMPOTENCY_CONFLICT409PATCH /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_REUSED409POST /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_FORBIDDEN403Todas 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_VIOLATION400POST /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_FOUND404GET /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_KIND400POST /imports.kind no es uno de los seis tipos de préstamo. La respuesta incluye un array allowed.
COMMIT_FAILED409POST /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ódigoEstadoDesencadenante
batch_too_large413El 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_required400Falta ?portfolioId=<UUID> o no es un UUID válido.
portfolio_not_found404El ?portfolioId= no existe como cartera activa en su organización.
invalid_body400El 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 filaDesencadenante
validation_failedLa fila no superó la validación del esquema. El campo message contiene los errores de validación.
fk_violationUna referencia de clave foránea de la fila (p. ej., borrowerId, loanId) no corresponde a una fila activa en la misma cartera.
unique_violationYa 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_violationFalló una regla de datos — normalmente la regla de condonación de un pago.
db_errorUn error inesperado al almacenar esta fila. La fila se notifica como fallida; el lote continúa.
invalid_jsonLa fila no era JSON válido. La plataforma procesa el resto del lote.

Códigos por fila de importaciones asíncronas

Código por filaDesencadenante
parse_errorLa línea no era JSON válido.
validation_errorLa fila no superó la validación del esquema.
portfolio_mismatchEl portfolioId de la fila no coincide con la cartera de anclaje de la importación.
processor_errorUn 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:

  1. Genere una Idempotency-Key determinista por operación lógica. Un UUIDv4 más un discriminador de ruta funciona.
  2. Envíe la solicitud con la clave.
  3. Ante cualquiera de 2xx, 409 ID_CONFLICT, 409 IDEMPOTENCY_CONFLICT, 409 IDEMPOTENCY_KEY_REUSED, 404, 403, 400, 413 o 422 — no reintente. El resultado es definitivo.
  4. Ante 429 — reintente tras el tiempo indicado en el encabezado Retry-After.
  5. Ante 500 o un error de red — reintente un número fijo y reducido de veces con espera exponencial. La Idempotency-Key hace 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 5xx como una funcionalidad. Un 500 es siempre un error que hay que corregir; nunca escriba lógica de cliente que dependa de una forma concreta de 500.
  • Ninguna respuesta 404 revela información de inquilinos. Un 404 sobre una fila que existe en otra organización es idéntico a un 404 sobre 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 id del cuerpo de la respuesta.