Erros

Quando algo dá errado, a API retorna um status HTTP de erro (4xx/5xx) e um corpo JSON no formato padrão abaixo.

Formato do erro

{
  "error": {
    "code": "CONFLICT",
    "message": "E-mail já cadastrado",
    "key": "errors.conflict.duplicate_email",
    "params": { "email": "joao@example.com" }
  }
}

Campo	Sempre presente	Descrição
`code`	Sim	Código estável e legível por máquina (ex.: `NOT_FOUND`, `VALIDATION_ERROR`).
`message`	Sim	Mensagem legível (fallback em pt-BR).
`issues`	Não	Lista dos campos que falharam na validação. Veja Erros de validação.
`key`	Não	Identifica o caso específico do erro, de forma estável. Veja Erros de domínio.
`params`	Não	Parâmetros de interpolação da mensagem (ex.: `{ "email": "..." }`).
`details`	Não	Detalhes adicionais, quando houver.

Programe sua lógica em cima do code (e do status HTTP), nunca do texto de message — o texto pode mudar ou vir traduzido.

Códigos HTTP

Status	Código típico	Significado	O que fazer
`400`	`VALIDATION_ERROR`	Corpo ou parâmetros inválidos.	Corrigir o payload. Ver `issues`.
`401`	— não tem `code`	API key ausente ou inválida.	Verificar o header `x-api-key`.
`403`	— não tem `code`	Sem permissão para a operação.	Verificar o tipo/escopo da chave.
`404`	`NOT_FOUND`	Recurso não existe (ou é de outra conta).	Conferir o ID.
`409`	`CONFLICT`	Conflito de estado (duplicado, transição inválida).	Tratar o caso específico.
`422`	— não tem `code`	Mesma `Idempotency-Key` reenviada com corpo diferente.	Usar uma chave nova para uma requisição nova. Veja Convenções · Idempotência.
`429`	— não tem `code`	Limite de requisições excedido. Veja Rate limit.	Aguardar `Retry-After` e repetir com backoff.
`500` / `502` / `503`	`INTERNAL_ERROR`	Erro no servidor.	Repetir com backoff; se persistir, contatar o suporte.

Quatro erros não seguem esse formato. O 401 e o 403 (autenticação), o 429 (limite de requisições) e os conflitos de idempotência — 422 para a mesma Idempotency-Key com corpo diferente, 409 para duas requisições simultâneas com a mesma chave — são interrompidos antes de chegar à aplicação. Neles, error vem como texto, não como objeto:

Formato normal

{ "error": { "code": "NOT_FOUND", "message": "Transaction not found" } }

401, 403, 422 e 429

{ "error": "Unauthorized" }

Na prática: error.code e error.message são undefined nesses casos. Um tratador genérico que leia error.code quebra — e quebra dentro do próprio tratamento de erro, escondendo o problema original. Para esses status, ramifique pelo status HTTP e leia os headers (Retry-After no 429). Veja Convenções · Idempotência.

Rate limit (`429`)

Requisições podem ser limitadas para proteger a plataforma. Os tetos variam por endpoint e podem mudar sem aviso, então trate o 429 em qualquer chamada em vez de assumir onde ele ocorre. Como nos outros erros de infraestrutura, error vem como texto, não como objeto:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 60s.",
  "retryAfter": 60
}

Headers relevantes:

Header	Descrição
`Retry-After`	Segundos até a janela do limite liberar (presente no `429`).
`X-RateLimit-Limit`	Limite de requisições da janela.
`X-RateLimit-Remaining`	Requisições restantes na janela atual.

Erros de validação (`400`)

Quando um ou mais campos são recusados, o corpo traz issues — uma lista com todos os problemas encontrados de uma vez, não só o primeiro:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "issues": [
      { "path": "items", "message": "É necessário pelo menos 1 item" },
      { "path": "", "message": "customer ou customerId é obrigatório" }
    ]
  }
}

Campo de `issues[]`	Descrição
`path`	Caminho do campo, com `.` separando níveis e o índice para arrays: `items.0.amount`, `payments.0.creditCard.token`. Veja a observação abaixo sobre o valor vazio.
`message`	Descrição do problema, já em texto legível.
`key`	Chave de i18n, quando disponível. Opcional.

A message do topo é genérica ("Validation failed") e não descreve o erro. O que interessa está em issues — não exiba a mensagem de fora para o usuário final achando que ela explica algo.

path vazio ("") significa erro que não pertence a um campo só. É o caso das regras que cruzam campos — por exemplo customer ou customerId é obrigatório, que depende dos dois. Ao montar a exibição do erro no seu sistema, trate o path vazio como um erro do formulário inteiro, e não de um campo específico.

Toda validação responde 400, venha ela do formato do payload ou de uma regra de negócio, e sempre neste mesmo formato. Um único tratamento cobre os dois casos.

Erros de domínio: a `key`

Alguns erros trazem um terceiro campo além de code e message: uma key estável, que identifica o caso específico.

{
  "error": {
    "code": "CONFLICT",
    "message": "Já existe um checkout com o slug \"minha-loja\"",
    "key": "errors.checkout.slug_taken"
  }
}

Os três campos respondem perguntas diferentes:

Campo	Para quê
`code`	A categoria. `CONFLICT`, `VALIDATION_ERROR`, `NOT_FOUND`… É por aqui que você decide o fluxo: repetir, corrigir o payload, avisar o usuário.
`key`	O caso exato. Use quando quiser substituir a nossa mensagem pela sua naquele cenário — `errors.checkout.slug_taken` é sempre esse conflito, e não outro.
`message`	O texto pronto, com fallback em pt-BR. Exiba se não quiser escrever o seu. Pode mudar sem aviso: não use em condicional.

A key não vai em code. Um erro de slug duplicado tem code: "CONFLICT" e key: "errors.checkout.slug_taken". Comparar error.code === "slug_taken" nunca casa — e falha em silêncio, porque o campo existe e simplesmente tem outro valor.

Cada página de endpoint lista os erros que aquela rota produz, com a key quando houver. Não há catálogo central: erros de domínio nascem e mudam com as regras de negócio, e uma lista mantida à mão desatualiza sem ninguém perceber.

Tratamento recomendado

Retry com backoff

Em 429 e 5xx, repita com backoff exponencial. Combine com Idempotency-Key para não duplicar a operação.

Não faça retry em 4xx

400, 409 e 422 não se resolvem repetindo a mesma requisição — corrija o payload ou trate o conflito.

Logue o code e o corpo

Guarde code, status HTTP e o corpo do erro para diagnóstico — em 400, guarde issues inteiro. Nunca logue a API key.

Idempotência sempre

Em escrita, use Idempotency-Key para que retries sejam seguros. Ver Convenções.

Começar aqui

Sandbox & Testes

Formato do erro

Códigos HTTP

Rate limit (`429`)

Erros de validação (`400`)

Erros de domínio: a `key`

Tratamento recomendado

Retry com backoff

Não faça retry em 4xx

Logue o code e o corpo

Idempotência sempre

​Formato do erro

​Códigos HTTP

​Rate limit (429)

​Erros de validação (400)

​Erros de domínio: a key

​Tratamento recomendado

Retry com backoff

Não faça retry em 4xx

Logue o code e o corpo

Idempotência sempre

Formato do erro

Códigos HTTP

Rate limit (`429`)

Erros de validação (`400`)

Erros de domínio: a `key`

Tratamento recomendado