Errores
Una sola forma de error para todos los endpoints, y los códigos sobre los que conviene bifurcar.
Todos los errores —validación, autenticación, no encontrado, límite de volumen, o nuestros— vuelven con el mismo body:
{
"error": {
"code": "CATALOG_PRODUCT_NOT_FOUND",
"message": "The catalog product does not exist."
}
}Bifurcá por code, nunca por message. El código es parte del contrato y no cambia abajo tuyo. El mensaje es una frase para alguien que lee un log, y lo reescribimos cada vez que aparece una más clara.
Códigos de estado
| Status | Qué significa |
|---|---|
400 | El request no es válido — un parámetro mal, un body mal armado, un contacto duplicado |
401 | La key falta, está mal formada, fue revocada o venció |
404 | Ese recurso no existe en esta organización. Puede existir en otra; el 404 es el mismo |
409 | Conflicto con el estado actual del recurso |
429 | Por encima del techo de requests — ver Límites de volumen |
5xx | Nuestro. Reintentá con backoff; si persiste, escribinos a support@trama.so |
Los códigos
| Código | Status | Cuándo |
|---|---|---|
VALIDATION_FAILED | 400 | Un parámetro o campo no pasó la validación. El mensaje nombra el campo: contacts.0.phone: Required |
CRM_CUSTOMER_DUPLICATE_IDENTIFIER | 400 | Otro cliente ya usa uno de esos contactos, o el mismo contacto viene repetido adentro de tu payload |
CRM_CUSTOMER_INVALID_PHONE | 400 | El teléfono del contacto no es usable |
API_KEY_MISSING | 401 | No vino ni Authorization ni x-api-key |
API_KEY_INVALID | 401 | La key no valida |
API_KEY_NOT_FOUND | 401 | La key fue revocada, o nunca existió |
CUSTOMER_NOT_FOUND | 404 | |
OPPORTUNITY_NOT_FOUND | 404 | |
CONVERSATION_NOT_FOUND | 404 | |
QUOTE_NOT_FOUND | 404 | |
CATALOG_PRODUCT_NOT_FOUND | 404 | |
NOT_FOUND | 404 | El endpoint no existe. Revisá el método y el path |
API_KEY_RATE_LIMITED | 429 | Ver Límites de volumen |
Un código que no reconocés igual se puede manejar. Se agregan códigos nuevos a medida que la API crece, así que tomá la lista de arriba como los que vale la pena bifurcar y todo lo demás como "un error de este status". Lo que no va a pasar es que un código existente cambie de significado.
Cómo se lee un error de validación
VALIDATION_FAILED pone el campo que falló adelante de todo, como un camino con puntos hacia lo que mandaste:
{ "error": { "code": "VALIDATION_FAILED", "message": "limit: Number must be less than or equal to 100" } }Ese camino es la parte útil. La frase que sigue sale del schema y puede reescribirse.
Lo que no vas a recibir
- Ni stack traces ni detalles internos. Un
5xxdice que el request no se pudo completar y nada más, a propósito. - Ningún texto de error en español. El panel está en español y el código de dominio abajo también; la API traduce en el borde, así que a quien integra nunca le llega un mensaje en un idioma que no pidió. Si alguno se escapa, es un bug y vale reportarlo.