Formato de erro e códigos de erro da API

Todas as respostas de erro da API têm o mesmo formato. O seu código deve basear-se no código de erro do campo error e não no texto de message – o código mantém-se estável, enquanto o texto pode mudar e é traduzido para o idioma da conta.

#Estrutura de uma resposta de erro

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

Código legível por máquina, por exemplo not_found. Na maioria dos erros está também no cabeçalho X-Error-Code – mas baseie-se no campo do corpo.

message

Descrição legível por pessoas no idioma da conta: com uma chave de API, o do proprietário do espaço de trabalho; com uma app ligada, o da pessoa que a ligou. Sem um token válido – por exemplo, no 401 da verificação do token –, o idioma segue Accept-Language; caso contrário, é inglês. O cabeçalho Content-Language indica o idioma.

details

Só existe quando há mais a dizer. Em 422 da validação de dados, é uma lista com field, reason e message para cada problema; em 422 da lógica de negócio e em todos os outros erros, é um objeto, por exemplo com reason, retry_after_sec ou uma lista de issues. Quando um tamanho é excedido, contém field, reason e limit, e em 413 request_too_large contém max_bytes e max_kb. Por isso, verifique se details é uma lista.

request_id

O ID do pedido. Está também no cabeçalho X-Request-Id. Indique-o quando contactar o suporte.

Exceções: a resposta 429 rate_limited tem o campo retry_after_sec em vez de details; em 429 e em 403 insufficient_scope, request_id não aparece no corpo. O 401 da verificação do token e o 422 da verificação do esquema não têm cabeçalho X-Error-Code; na verificação do esquema, só o message de nível superior é traduzido, os textos em details ficam em inglês. O cabeçalho X-Request-Id está sempre definido.

#Os códigos mais importantes

#Ler erros de dados

Com 422 validation_failed, details lista cada problema em separado: field é o caminho do campo (com barras para objetos aninhados, por exemplo theme_config/button_style), reason é a regra violada, como required, minLength, maxLength, enum ou additionalProperties. Com additionalProperties, message indica quais os campos desconhecidos – muitas vezes trata-se de um erro de escrita no nome do campo.

#Tratamento recomendado no seu código

• 400, 413 e 422: não repetir, corrigir antes o pedido
• 401 invalid_token: obter um novo token uma vez e repetir
• 403: não repetir; verificar o scope, o plano ou quem tem permissão para isto
• 404: verificar o ID; depois de uma eliminação, isto é normal
• 409: recarregar o estado e decidir se a ação ainda é necessária
• 429: esperar o tempo indicado em Retry-After e depois repetir – veja Rate limits
• 500 e 503: repetir algumas vezes com pausas crescentes