Convenções e erros

Headers

Header	Valor	Observação
`Authorization`	`Bearer {access_token}`	Token da aplicação. Veja Autenticação.
`x-api-version`	`2.0`	Obrigatório em toda chamada. Sem ele (ou com ele vazio), a resposta é `400` com `code` `API_VERSION_REQUIRED`.
`Content-Type`	`application/json`	Em requisições com corpo (POST e PUT).

Sem o x-api-version, a resposta é:

{
  "code": "API_VERSION_REQUIRED",
  "displayMessage": "Envie o header x-api-version: 2.0"
}

Status HTTP

Use o status HTTP para saber se a operação deu certo: 2xx é sucesso; 4xx e 5xx são falhas e trazem um corpo de erro.

Status	Quando acontece
`400`	Requisição inválida: corpo, parâmetros ou regra de negócio, ou falta do `x-api-version`.
`401`	Token ausente, inválido ou expirado (`SESSION_INVALID`), ou os perfis de acesso da aplicação não permitem o endpoint (`UNAUTHORIZED`).
`404`	Recurso não encontrado.
`409`	Conflito com o estado atual do recurso.
`500`	Erro inesperado. Tente de novo; se persistir, contate o suporte.

Formatos de erro

A Admin API tem dois formatos de corpo de erro. A página de cada módulo e a Referência de API indicam qual ele usa.

Formato padrão

Usado pelas rotas de Promoções (/api/promotions/*). Campos em camelCase:

{
  "code": "VALIDATION_FAILED",
  "displayMessage": "Falha na validação!",
  "details": [
    { "field": "disclosure[0].title", "code": "VALIDATION_FAILED", "issue": "Título da divulgação não pode ultrapassar 50 caracteres." }
  ],
  "traceId": "0HN7…:00000001"
}

Campo	Descrição
`code`	Categoria da falha, derivada do status (ex.: `VALIDATION_FAILED`, `SESSION_INVALID`, `UNAUTHORIZED`, `NOT_FOUND`, `CONFLICT`, `INTERNAL_ERROR`).
`displayMessage`	Mensagem em português que pode ser exibida ao usuário.
`details`	Lista de problemas. Omitido quando não há detalhes. Cada item tem `code`, `issue` (o motivo) e, quando o problema é de um campo, `field` (caminho em camelCase).
`traceId`	Identificador da requisição. Informe-o ao suporte.

Formato legado

Usado pelas demais rotas. Campos em PascalCase:

{
  "DisplayMessage": "Ops, Aconteceu um erro! Tente novamente mais tarde.",
  "Code": "SESSION_INVALID"
}

Campo	Descrição
`DisplayMessage`	Mensagem em português que pode ser exibida ao usuário.
`Code`	Código da falha. Omitido quando não há código.
`Data`	Dados adicionais sobre a falha, em alguns endpoints. Omitido quando não há dados.