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 GET também pode receber 503, por outro motivo. Se a validação da sua chave em si não puder acontecer (uma piscada no nosso banco), a resposta é 503 em 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". Em 503, sempre repita, nunca conclua que a chave morreu.

429 significa esperar, não desistir. Veja o cabeçalho x-ratelimit-reset.