Manejo de errores

Códigos de estado HTTP estándar, el cuerpo JSON de error y la taxonomía de `key`.

Guía

La API usa códigos de estado HTTP estándar. Un 2xx indica éxito; un 4xx que revises tu solicitud; un 5xx que el problema está del lado de Mendel.

Códigos que devuelve cualquier endpoint

Estos cinco están declarados en las 55 operaciones de la Referencia.

Código	Significado	Cuerpo	Qué hacer
`400 Bad Request`	La solicitud está mal formada o un dato no pasó las validaciones.	Sí	El cuerpo indica el campo o la regla que falló.
`401 Unauthorized`	Falta la API key o no es válida.	Sin cuerpo	Verifica el header `X-API-KEY` y que la key sea del entorno correcto.
`403 Forbidden`	La key es válida pero no tiene permiso sobre ese recurso.	A veces	Confirma el alcance de tu key con Mendel. No reintentes sin cambiarla.
`500 Internal Server Error`	Error inesperado del lado de Mendel.	Sin cuerpo	Reintenta; si persiste, contacta a soporte con la ruta y la hora.
`504 Gateway Timeout`	Un servicio interno no respondió a tiempo.	Sin cuerpo	En escrituras, verifica el estado antes de reintentar: la operación pudo haberse aplicado.

Códigos que dependen del recurso

Estos no están en todas las operaciones. La Referencia los lista en cada una que puede devolverlos, así que ese es el lugar donde confirmarlo.

Código	Dónde aplica	Significado
`404 Not Found`	Operaciones con un `{code}` en la ruta	El recurso no existe, o no es visible para tu empresa.

Un endpoint no devuelve 404 aunque tenga {code}

GET /purchases/{code}/files responde 200 con un conjunto de archivos vacío cuando la transacción no existe, en lugar de 404. Sus operaciones hermanas (GET /purchases/{code} y PATCH /purchases/{code}) sí devuelven 404. Si necesitas distinguir "transacción sin archivos" de "transacción inexistente", consulta primero GET /purchases/{code}.

No hay un 422

Las validaciones fallidas se devuelven como 400, no como 422: ninguna operación de la API declara 422. Si tu integración distingue esos casos, trata 400 como el único código de validación.

Cuerpo de error

Hoy conviven dos formas de cuerpo, y el significado de key cambia entre ellas. La Referencia documenta ambas en cada operación.

Forma 1 — error de dominio. key es un código de error de un conjunto cerrado (ver la taxonomía más abajo):

{
  "errors": [
    { "key": "NOT_FOUND", "parameters": [] }
  ]
}

Forma 2 — validación de formato. Agrega status, y key pasa a ser el nombre del campo que falló, con el mensaje en category:

{
  "status": 400,
  "errors": [
    { "category": "must not be blank", "key": "name", "parameters": [] }
  ]
}

Un error puede traer además description. parameters lleva los valores que se interpolan en el mensaje.

Programa contra el código de estado, no contra `key`

Como key significa dos cosas distintas según la forma, no es un campo estable para ramificar tu lógica. Usa el código de estado HTTP para decidir el flujo y lee errors[].key de forma defensiva (puede ser un código o un nombre de campo). Unificar el cuerpo de error está planificado para una próxima versión de la API.

Taxonomía de `key`

En la forma 1, key sale de un conjunto cerrado y estable:

`key`	Significado
`NOT_FOUND`	El recurso referenciado no existe o no es visible para tu empresa.
`NOT_ALLOWED`	La operación no está permitida sobre ese recurso o con esos datos.
`DUPLICATE`	Ya existe un recurso con ese identificador o esa combinación de datos.
`UNEXPECTED_ERROR`	Falla no clasificada al procesar la solicitud.
`INVALID_IMPERSONATION`	La suplantación solicitada no es válida para tu key.

La lista no es exhaustiva

Algunas operaciones propagan errores de validación de los servicios internos que consultan, con key propias de esos servicios. Y en la forma 2, key es un nombre de campo, así que es un conjunto abierto por definición. Trata cualquier key que no reconozcas como un error genérico del código de estado que la acompaña, en lugar de asumir que la lista de arriba está completa.

Casos particulares

Parámetros de consulta mal formados. Un valor inválido en un query param (por ejemplo, una fecha con formato incorrecto) devuelve 400 con la forma 2, identificando el parámetro en key.

401 vs 403. 401 es un problema de autenticación (quién eres): la key falta o es inválida. 403 es de autorización (qué puedes hacer): la key es válida pero no alcanza para ese recurso. No reintentes un 403 sin cambiar de credencial o de alcance.

Límites de tasa. La API pública no publica un límite de tasa y ninguna operación declara 429. Si aun así recibes uno, aplica backoff exponencial.