Formato de erros, códigos HTTP, rate limits, idempotência e boas práticas de integração.
Formato de ErroTodos os erros seguem o mesmo formato JSON. O campo 'error' sempre está presente. Para erros de validação, o campo 'details' contém um mapa campo → mensagem.
// Erro simples
{
"error": "Invalid credentials"
}
// Erro de validação (400)
{
"error": "Validation failed",
"details": {
"email": "Email inválido",
"phone": "Telefone deve ter 11 dígitos",
"tax_id": "CPF inválido"
}
}
// Erro de conflito (409)
{
"error": "Email already registered"
}CÓDIGO SIGNIFICADO QUANDO ACONTECE ───────────────────────────────────────────────────── 200 OK Sucesso em GET/PUT/DELETE 201 Created Recurso criado (POST) 400 Bad Request Validação falhou / JSON inválido 401 Unauthorized Token expirado ou ausente 403 Forbidden CSRF inválido / sem permissão 404 Not Found Recurso não existe 409 Conflict Email duplicado / ingresso já usado 422 Unprocessable Entity Regra de negócio violada 429 Too Many Requests Rate limit excedido 500 Internal Server Error Bug no servidor (reporte)
Rate LimitsRate limits protegem a API contra abuso. Limites são por IP (endpoints públicos) ou por tenant (endpoints autenticados). Quando excedido, aguarde o tempo indicado no header Retry-After.
ENDPOINT LIMITE ESCOPO ────────────────────────────────────────────────────────── POST /auth/register 5 req / 15 min Por IP POST /auth/request-otp 10 req / 15 min Por IP POST /public/purchase 30 req / min Por IP GET /public/* 60 req / min Por IP POST/PUT/DELETE (auth) 100 req / min Por tenant GET (autenticado) 200 req / min Por tenant Headers de resposta: X-RateLimit-Limit: 100 X-RateLimit-Remaining: 47 X-RateLimit-Reset: 1711234567
// Quando excedido:
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711234567
{
"error": "Rate limit exceeded"
}
// Dica: implemente exponential backoff
// Espere Retry-After segundos antes de tentar novamenteX-Idempotency-KeyTodas as requisições POST/PUT/PATCH suportam o header X-Idempotency-Key. Se a mesma chave for enviada novamente em 24h, a resposta original é retornada sem reprocessar. Essencial para evitar cobranças duplicadas.
curl -X POST https://api.flair.api.br/api/v1/events \
-H "Authorization: Bearer TOKEN" \
-H "X-Idempotency-Key: unique-key-123" \
-H "Content-Type: application/json" \
-d '{
"name": "Meu Evento",
"event_date": "2026-07-15T18:00:00Z"
}'// Primeira chamada: cria o evento normalmente // Segunda chamada com mesma key (em até 24h): // → Retorna a MESMA resposta da primeira chamada // → NÃO cria duplicata // → Status code original é preservado // Use cases: // - Retry após timeout de rede // - Garantir que purchase não é cobrada 2x // - Proteção contra double-click
CSRF ProtectionEndpoints autenticados (POST/PUT/DELETE) exigem um token CSRF válido. O token é obtido via header X-CSRF-Token em qualquer GET autenticado, e deve ser enviado de volta no mesmo header. Tokens são single-use.
# 1. Obter token CSRF (qualquer GET autenticado)
curl https://api.flair.api.br/api/v1/profile \
-H "Authorization: Bearer TOKEN"
# → Response header: X-CSRF-Token: abc123...
# 2. Usar token no POST
curl -X POST https://api.flair.api.br/api/v1/events \
-H "Authorization: Bearer TOKEN" \
-H "X-CSRF-Token: abc123..." \
-H "Content-Type: application/json" \
-d '{ "name": "Meu Evento" }'// Token CSRF inválido ou ausente:
HTTP/1.1 403 Forbidden
{
"error": "CSRF token missing"
}
// Token não bate com cookie:
HTTP/1.1 403 Forbidden
{
"error": "CSRF token mismatch"
}
// Dica: obtenha um novo token CSRF
// antes de CADA request mutanteNossa infraestrutura global processa milhões de requisições simultâneas em horários de pico. Junte-se a +500 promotores usando Flair.
Uptime Garantido