Lista de errores de Lender

Busca cada estado HTTP que devuelve la API de Lender, la condición que hay detrás y la acción que la resuelve.

Formato del error

Lender devuelve la mayoría de los errores como detalles de problema RFC 9457 con el tipo de medio application/problem+json. Un rechazo por límite de tasa responde con un cuerpo plano {code, title, message} en application/json.

Problem detail

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    {
      "location": "body.grossRequestedAmount",
      "message": "expected string",
      "value": 50000
    }
  ]
}

Definiciones de los campos

• code – El código de dominio estable y legible por máquina que lleva el rechazo, con el formato LENDER-NNNN. Ausente cuando al rechazo no se le asignó uno. Ramifica primero por él.
• status – El código de estado HTTP.
• title – El nombre del estado, como Unprocessable Entity.
• detail – Qué salió mal en esta ocurrencia. Por debajo de 500, describe el rechazo específico. Para 500, 502 y 503, lleva un valor genérico fijo en lugar de la causa subyacente.
• errors – Lista opcional de detalles de validación de esquema. Cada entrada lleva un location, un message y el value que recibió Lender.
• type – https://errors.lerian.studio/v1/LENDER-NNNN cuando code está presente. El valor predeterminado de RFC 9457 about:blank en caso contrario.

El cuerpo plano del límite de tasa lleva en cambio code, title y message. Su code repite el estado HTTP numérico. Su title nombra el rechazo y su message lo explica en una sola frase. Ninguna de las dos cadenas varía según quien llama, ni indica la cuota que te queda.

Ramifica por code cuando la respuesta lleve uno, y por el estado HTTP y el tipo de contenido cuando no. Lee detail solo como prosa para una persona. El middleware de autorización y de idempotencia puede responder en sus propios formatos de respuesta.

​

Errores del cliente

---

Lender responde con un 4xx cuando el problema es la solicitud, y detail nombra el rechazo específico.

Lender limita una búsqueda al tenant de quien llama y al padre nombrado en la ruta. Un identificador que resuelve fuera de ese ámbito responde igual que un identificador que no resuelve a nada.

Un comando necesita un subject en la identidad de quien llama, porque Lender registra ese subject como el actor detrás del cambio. Los límites de bytes se aplican dos veces: el framework limita el cuerpo de la solicitud, y cada superficie de ingesta de archivos limita el archivo que acepta.

La validación de esquema se ejecuta antes del handler y llena errors con una entrada por cada ubicación rechazada. Una regla de negocio se ejecuta dentro del handler y responde solo con detail. Tres ejemplos: una aserción de moneda que no coincide con el préstamo, una composición de conjunto que mezcla monedas, y un fondo configurado sin registro.

Estado	Qué significa	Qué hacer
400	La solicitud llega sin cuerpo, o el cuerpo no tiene la forma JSON exacta que la operación lee.	Envía un cuerpo que coincida con el esquema de la operación y repite la solicitud.
400	El header X-Idempotency es más largo de lo que acepta la operación.	Envía una clave más corta y repite la solicitud.
401	La solicitud llega sin una identidad autenticada.	Envía un token bearer válido y repite la solicitud.
401	La identidad está autenticada, y su subject está vacío.	Usa un token cuyo subject identifique a quien llama.
403	La solicitud carece de una identidad de tenant validada para el recurso sobre el que opera la operación.	Usa un token con ámbito en el tenant que posee el recurso, y repite la solicitud.
404	El identificador en la ruta nombra un recurso que este tenant no posee.	Revisa el identificador y revisa el tenant al que tiene ámbito el token.
404	El recurso existe, y el padre nombrado en la ruta no lo posee.	Lista los recursos propios del padre y usa un identificador de esa lista.
409	Otra solicitud con el mismo valor X-Idempotency todavía se está ejecutando.	Espera el intervalo de Retry-After y luego lee el recurso. No vuelvas a enviar el comando.
422	El valor X-Idempotency ya se usó para una solicitud con un cuerpo diferente.	No envíes este comando con una clave nueva. Lee primero el resultado de la solicitud original y luego decide.
409	El idempotencyKey en el cuerpo nombra un término ya registrado con contenido diferente.	Lee el término registrado. Una clave nueva registra un segundo término para el mismo conjunto.
409	El recurso se encuentra en un paso distinto del ciclo de vida, o ya se cerró.	Lee el recurso y actúa según el paso en el que se encuentra.
409	Otro escritor cambió el recurso durante la solicitud.	Vuelve a leer el recurso y repite la solicitud.
409	Un registro externo ya aceptó este comando exacto.	Lee el protocolo registrado en lugar de emitir el comando de nuevo.
413	El cuerpo de la solicitud es más grande de lo que acepta la operación.	Envía un cuerpo más pequeño.
413	El archivo cargado es más grande de lo que acepta la superficie de ingesta.	Envía un archivo más pequeño.
405	La ruta existe, y no acepta este método HTTP.	Usa un método que la operación declare en la referencia de API.
415	El header Content-Type nombra un formato que la operación no lee.	Envía application/json.
429	Quien llama envió más solicitudes de las que permite el límite de tasa del despliegue.	Lee el header Retry-After, espera esa cantidad de segundos y repite la solicitud.
422	La solicitud no coincide con el esquema de la operación.	Corrige cada entrada en errors y repite la solicitud.
422	La solicitud coincide con el esquema, y una regla de negocio rechaza su contenido.	Lee detail, corrige la solicitud y envíala de nuevo.
409	Un comando alcanzó un recurso que ya está cerrado, y no es la reentrega del comando que lo cerró.	Reentregar el comando original bajo la misma identidad de solicitud responde 200 con el registro que ya rige. Este estado significa un segundo comando, distinto. Lee el registro y luego decide; nada se contabilizó dos veces.
409	El rechazo es reproducible: repetir la solicitud reproduce el conflicto.	No la repitas. El estado contra el que se construyó la solicitud cambió, así que concilia el registro y emite el comando que pide el estado actual.
422	El rechazo es terminal por diseño: la solicitud nunca tendrá éxito tal como está.	No la reenvíes, con o sin correcciones. detail nombra el caso. La operación rechazó en lugar de dejar el recurso a medias, y el recurso está exactamente como estaba.
422	El rechazo nombra configuración del despliegue o de operación, no una solicitud malformada.	Corregir el cuerpo no ayuda. detail nombra el objeto y el estado en el que está. Ajusta la configuración y envía de nuevo la solicitud original.

​

Errores del servidor

---

Lender responde con un 5xx cuando la solicitud es correcta y la llamada no pudo completarse. Para estos estados, detail lleva un valor genérico fijo, de modo que la causa subyacente permanece dentro del servicio.

Un 503 cubre dos condiciones: una capacidad que el despliegue no ejecuta, y una dependencia que Lender no puede alcanzar en el momento de la llamada. Un 502 cubre a un tercero que rechaza un comando que Lender le reenvía, como el registro que asienta una cesión de cuentas por cobrar.

Estado	Qué significa	Qué hacer
500	Lender no pudo completar la solicitud.	En una lectura, repite la solicitud. En un comando que mueve dinero, lee primero el recurso y repite solo si el comando no se aplicó. Si el estado se repite, contacta a soporte con la operación, el tenant y la hora de la llamada.
502	El registro al que Lender reenvía rechazó el comando.	La respuesta no nombra el motivo. Revisa la configuración del registro del fondo y los datos del comando, y emite el comando de nuevo.
503	El despliegue no ejecuta la capacidad que la operación necesita.	Pide a tu equipo de plataforma que habilite la capacidad para tu despliegue.
503	Un almacén de datos o una dependencia downstream no estaban disponibles.	Vuelve a intentarlo con backoff.