Erros e respostas

Envelope JSON padronizado e códigos HTTP da API Arena.

Envelope

Sucesso

{
  "status": "success",
  "data": { },
  "meta": { "request_id": "…" }
}

Erro

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Descrição legível",
    "details": ["…opcional…"]
  },
  "meta": { "request_id": "…" }
}

O header X-Request-Id espelha meta.request_id para suporte/logs.

Códigos

HTTP	Código	Quando
401	`UNAUTHORIZED`	API key ausente ou inválida
403	`FORBIDDEN`	Escopo insuficiente (ex.: falta `ranking.entries.write`)
404	`NOT_FOUND`	Campanha ou vendedor não encontrado / inativo; sem campanha ativa
400 / 422	`VALIDATION_ERROR`	JSON inválido, campos obrigatórios, método errado
405	`VALIDATION_ERROR`	Método HTTP não permitido
500	`INTERNAL_ERROR`	Falha inesperada no servidor

Boas práticas

Trate 401 como “renovar/revogar chave” em App → API.
Use idempotency_key por evento de venda no CRM.
Logue request_id no lado do cliente para abrir chamado com contexto.
Health (GET /api/v1/health) não exige auth — útil para monitoramento.

Swagger ao vivo Voltar à visão geral