Erros
Toda falha devolve o mesmo envelope:
Toda falha devolve o mesmo envelope:
{
"error": {
"code": "validation_error",
"message": "Nome obrigatório"
}
}A message é sempre segura para exibir na sua interface.
| HTTP | code |
Quando acontece |
|---|---|---|
| 400 | validation_error |
Corpo ou parâmetros inválidos — a mensagem diz qual campo |
| 400 | unknown_field |
O corpo trouxe uma chave que este endpoint não conhece. ⛒ É o erro mais provável da sua primeira integração: todo campo com nome errado — ou no lugar errado dentro do corpo — recusa a chamada em vez de ser descartado em silêncio. A mensagem nomeia o campo, com o caminho (ex.: deal.custom_fields) |
| 400 | forbidden_import_field |
Você mandou um campo de importação (created_at, updated_at, author_id, author_name, attachments, completed_at, actual_close_date) numa chave sem o escopo import:write (§24). Nomeia o campo, e nada é gravado |
| 401 | unauthorized |
Chave ausente, inválida ou revogada |
| 402 | account_suspended |
A assinatura desta conta está suspensa ou cancelada |
| 403 | forbidden_scope |
A chave não tem o escopo necessário |
| 403 | key_actor_invalid |
O responsável pela chave não é mais membro ativo da conta |
| 403 | forbidden_module |
As permissões do responsável pela chave negam esta ação |
| 403 | module_not_in_plan |
O plano da sua conta não inclui esse módulo — aqui não adianta mexer em permissão, é contratar |
| 404 | not_found |
Não existe, não é da sua conta, ou é de outro responsável |
| 409 | conflict |
Conflito de estado — veja cada recurso (ex.: SKU de produto ou nome de categoria já usados) |
| 422 | validation_error |
O corpo está certo, mas o estado do registro não aceita a operação — ex.: lançar contagem de estoque num produto que não controla estoque |
| 405 | validation_error |
Método HTTP errado nesta rota — a resposta traz o cabeçalho Allow com os aceitos |
| 409 | external_id_conflict |
O external_id que você mandou já pertence a outro registro da sua conta. ⛒ A resposta traz o existing_id — é o que faz uma carga ser reexecutável: ao receber isto, reuse o registro que já existe, não tente com um id novo (§27) |
| 409 | external_id_immutable |
Um PATCH tentou trocar o external_id de um registro que já tem um. Definir pela primeira vez pode; trocar, não |
| 409 | cnpj_conflict |
Já existe empresa na sua conta com esse CNPJ. Também traz o existing_id |
| 429 | rate_limited |
Limite de requisições excedido — ver §4 |
| 500 | internal_error |
Erro inesperado. Em produtos, se vier com o cabeçalho x-salos-partial-write: true, parte da operação já foi gravada — confira antes de repetir (a resposta traz o product_id quando o produto chegou a ser criado) |
| 503 | internal_error |
Um controle de proteção está degradado — tente de novo em instantes |
Três respostas que costumam ser mal interpretadas
402 não é problema de chave. Sua chave está boa; a assinatura da conta é que está suspensa
por falta de pagamento. Devolvemos 402 em vez de 401 de propósito — a maioria das ferramentas
de automação desabilita a conexão sozinha ao ver um 401, e regularizar o pagamento não
bastaria para reativar. Atraso recente que ainda não virou suspensão passa normalmente.
503 em escrita não quer dizer que sua chave falhou. Ele aparece em POST, PATCH e
DELETE quando um dos nossos controles de proteção — o de duplicidade ou o contador de limite —
não conseguiu confirmar naquele instante. Preferimos recusar a executar sem rede de segurança.
GET não é bloqueado por esse motivo: ler não duplica nada.
Mas
GETtambém pode receber503, por outro motivo. Se a validação da sua chave em si não puder acontecer (uma piscada no nosso banco), a resposta é503em qualquer método, inclusive leitura — é a diferença entre "sua chave está errada" (401, que faz a sua ferramenta desabilitar a conexão) e "não deu pra conferir agora, tente de novo". Em503, sempre repita, nunca conclua que a chave morreu.
429 significa esperar, não desistir. Veja o cabeçalho x-ratelimit-reset.