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`)
429	`RATE_LIMITED`	Limite de requisições por chave/janela excedido (veja `Retry-After`)
404	`NOT_FOUND`	Recurso inexistente ou de outra empresa (anti-IDOR — mensagem genérica)
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

Anti-IDOR

A chave fixa o tenant. Qualquer user_id, campaign_id, tier_id etc. fora dessa empresa responde 404 — nunca 403 do tipo “existe em outra empresa”.

Listagens sempre filtradas por company_id da chave.
Updates/deletes com WHERE id = ? AND company_id = ?; zero linhas → 404.
Sem user_id/external_code onde obrigatório → 400 VALIDATION_ERROR.

Boas práticas

Trate 401 como “renovar/revogar chave” em App → API.
Use idempotency_key por evento de venda no CRM.
Prefira external_code estável do CRM em vez de IDs internos.
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