Erros

A API v1 retorna os erros em JSON dentro da propriedade error:

{
  "error": {
    "code": "api_unauthorized",
    "message": "Authentication required."
  }
}

code é o valor legível por máquina. message é uma descrição curta. Alguns erros também incluem details e correlation_id.

Códigos de status

Use o status HTTP e error.code em conjunto:

Status	Significado
`400`	Não foi possível interpretar a requisição.
`401`	A requisição não tem uma credencial de API aceita.
`403`	A credencial não tem o escopo ou o acesso à conta necessário.
`404`	O recurso solicitado não foi encontrado.
`409`	A alteração solicitada entra em conflito com o estado atual.
`413`	O corpo da requisição excede um limite.
`415`	O corpo da requisição não usa um tipo de conteúdo JSON aceito.
`422`	A requisição não corresponde ao contrato do endpoint.
`429`	Um limite de requisições bloqueou a operação.
`500`	A API não conseguiu produzir uma resposta válida.
`503`	Um serviço necessário estava indisponível.

A referência de cada endpoint lista os códigos de erro que ele pode retornar.

IDs de correlação

Todas as respostas da API v1 incluem X-Correlation-ID. O corpo de um erro também pode trazer o mesmo valor em error.correlation_id. Ao investigar uma falha, registre o ID de correlação junto com o código de status e o error.code. Não registre a credencial Bearer nem campos da resposta que possam conter dados pessoais.

Decisões de nova tentativa

Para 429, aguarde o número de segundos indicado em Retry-After antes de tentar novamente.
Para 503, não trate a resposta como uma redefinição de cota. Uma falha do limitador usa rate_limiter_unavailable e não inclui Retry-After.
Para 401 ou 403, corrija a credencial, o escopo ou o acesso à conta em vez de repetir a mesma requisição.
Para 422, corrija a requisição conforme a referência do endpoint.

Leia Limites de requisição para entender o comportamento completo do 429.

Visão geral

Primeiros passos

Guias

Webhooks

Códigos de status

IDs de correlação

Decisões de nova tentativa

​Códigos de status

​IDs de correlação

​Decisões de nova tentativa

Códigos de status

IDs de correlação

Decisões de nova tentativa