Erros
Um único formato de erro para todos os endpoints, e os códigos nos quais vale ramificar.
Todos os erros — validação, autenticação, não encontrado, limite de volume, ou nossos — voltam com o mesmo corpo:
{
"error": {
"code": "CATALOG_PRODUCT_NOT_FOUND",
"message": "The catalog product does not exist."
}
}Ramifique por code, nunca por message. O código faz parte do contrato e não muda embaixo de você. A mensagem é uma frase para quem lê um log, e nós a reescrevemos sempre que aparece uma mais clara.
Códigos de status
| Status | O que significa |
|---|---|
400 | A requisição não é válida — um parâmetro errado, um corpo malformado, um contato duplicado |
401 | A chave falta, está malformada, foi revogada ou venceu |
404 | Esse recurso não existe nesta organização. Pode existir em outra; o 404 é o mesmo |
409 | Conflito com o estado atual do recurso |
429 | Acima do teto de requisições — ver Limites de volume |
5xx | Nosso. Tente de novo com backoff; se persistir, escreva para support@trama.so |
Os códigos
| Código | Status | Quando |
|---|---|---|
VALIDATION_FAILED | 400 | Um parâmetro ou campo não passou na validação. A mensagem nomeia o campo: contacts.0.phone: Required |
CRM_CUSTOMER_DUPLICATE_IDENTIFIER | 400 | Outro cliente já usa um desses contatos, ou o mesmo contato vem repetido dentro do seu payload |
CRM_CUSTOMER_INVALID_PHONE | 400 | O telefone do contato não é utilizável |
API_KEY_MISSING | 401 | Não veio nem Authorization nem x-api-key |
API_KEY_INVALID | 401 | A chave não valida |
API_KEY_NOT_FOUND | 401 | A chave foi revogada, ou nunca existiu |
CUSTOMER_NOT_FOUND | 404 | |
OPPORTUNITY_NOT_FOUND | 404 | |
CONVERSATION_NOT_FOUND | 404 | |
QUOTE_NOT_FOUND | 404 | |
CATALOG_PRODUCT_NOT_FOUND | 404 | |
NOT_FOUND | 404 | O endpoint não existe. Confira o método e o caminho |
API_KEY_RATE_LIMITED | 429 | Ver Limites de volume |
Um código que você não reconhece ainda assim pode ser tratado. Códigos novos entram conforme a API cresce, então trate a lista acima como os que vale ramificar e todo o resto como "um erro deste status". O que não vai acontecer é um código existente mudar de significado.
Como se lê um erro de validação
VALIDATION_FAILED coloca o campo que falhou na frente de tudo, como um caminho com pontos dentro do que você enviou:
{ "error": { "code": "VALIDATION_FAILED", "message": "limit: Number must be less than or equal to 100" } }Esse caminho é a parte útil. A frase seguinte sai do schema e pode ser reescrita.
O que você não vai receber
- Nem stack traces nem detalhes internos. Um
5xxdiz que a requisição não pôde ser concluída e nada mais, de propósito. - Nenhum texto de erro em espanhol. O painel está em espanhol e o código de domínio embaixo dele também; a API traduz na fronteira, então quem integra nunca recebe uma mensagem num idioma que não pediu. Se alguma escapar, é um bug e vale reportar.