Erros da API

Todos os endpoints da API retornam erros no mesmo formato JSON. Esta página documenta o formato, os códigos usados, a proteção CSRF e os headers de cota.

Formato padrão

Toda resposta de erro segue o schema APIErrorResponse — dois campos, sempre presentes:

{
  "error": "quota_exceeded",
  "message": "You have reached your API request limit for this billing period. Upgrade to continue."
}

error — código estável, feito para tratamento programático. Ramifique a sua lógica por ele, nunca pelo texto.
message — descrição legível, sujeita a mudança sem aviso.

Em erros 5xx a mensagem é sempre genérica (“An internal error occurred. Please try again later.”) — detalhes internos nunca vazam no corpo da resposta.

Códigos de erro

`error`	Significado
`invalid_request`	Corpo, parâmetro ou query inválidos — inclui corpo grande demais (`413`).
`unauthorized`	Sessão/API Key/token de site ausente, inválido ou revogado.
`forbidden`	Autenticado, mas sem permissão — inclui falha de CSRF e conta inativa.
`email_not_verified`	O e-mail da conta ainda não foi confirmado.
`plan_required`	Assinatura inexistente, cancelada ou expirada.
`plan_limit_exceeded`	Recurso fora do plano ou limite do plano atingido (ex.: número de sites).
`quota_exceeded`	Cota mensal de requisições da API esgotada.
`too_many_requests`	Rate limit por janela de tempo em endpoint sensível.
`not_found`	Recurso inexistente ou não pertencente à sua conta.
`conflict`	Estado incompatível com a operação (ex.: export ainda não pronto).
`subscription_exists`	Já existe assinatura ativa; use a troca de plano.
`already_on_plan`	Você já está no plano solicitado.
`internal_error`	Falha interna. Tente novamente; se persistir, contate o suporte.

Status HTTP

Status	Quando ocorre	Códigos típicos
`400`	Corpo/query malformados, validação de campos, cursor inválido.	`invalid_request`
`401`	Sem autenticação válida: API Key revogada, sessão expirada, `X-Site-Token` inválido no ingest público.	`unauthorized`
`402`	Assinatura não está ativa.	`plan_required`
`403`	CSRF ausente/inválido, e-mail não verificado, conta inativa, recurso fora do plano.	`forbidden`, `email_not_verified`, `plan_limit_exceeded`
`404`	Recurso não existe ou não é seu — a API não distingue os dois casos.	`not_found`
`409`	Conflito de estado (assinatura duplicada, export não finalizado).	`conflict`, `subscription_exists`
`413`	Corpo maior que o limite da rota (ver Limites de corpo).	`invalid_request`
`429`	Rate limit por janela ou cota mensal esgotada — distinga pelo código.	`too_many_requests`, `quota_exceeded`
`5xx`	Falha interna; mensagem sempre genérica.	`internal_error`

CSRF (`403`)

Requisições de escrita (POST/PUT/PATCH/DELETE) autenticadas por cookie de sessão exigem o padrão double-submit cookie:

O backend entrega um cookie csrf_token legível por JavaScript (deliberadamente não HttpOnly).
O cliente ecoa o valor do cookie no header X-CSRF-Token em toda mutação.
Header ausente ou diferente do cookie → 403 com {"error": "forbidden", "message": "CSRF token missing or invalid"}.

Métodos de leitura (GET/HEAD/OPTIONS) nunca passam pela verificação.

Chamadas com API Key são isentas de CSRF. Tráfego server-to-server não tem contexto de navegador nem cookies ambientes — a autenticação já é um header Authorization explícito que um atacante precisaria possuir de qualquer forma. Se você integra apenas via Bearer sk-..., pode ignorar esta seção.

Se o seu backend recebe 403 de CSRF, você provavelmente está autenticando com cookie sem querer — use API Key para integrações server-to-server.

Headers `X-RateLimit-*`

Respostas de rotas medidas por cota (chamadas com API Key aos grupos /consents, /policies e /exports) trazem três headers, na convenção GitHub/Stripe:

Header	Semântica
`X-RateLimit-Limit`	Cota de requisições do período de cobrança. `0` significa ilimitado (plano sem teto).
`X-RateLimit-Used`	Requisições já consumidas no período.
`X-RateLimit-Remaining`	Restante, nunca negativo. Quando `Limit` é `0` (ilimitado), vem `0` — ignore-o nesse caso e use `Limit: 0` como sinal.

Use-os para se auto-regular sem precisar consultar o estado do plano. Chamadas do dashboard (cookie) não consomem cota e não recebem esses headers. Quando a cota esgota, a API responde 429 com quota_exceeded. Os rate limits por janela de tempo (too_many_requests) são independentes da cota mensal: endpoints sensíveis (login, recuperação de senha, contato) têm limites por IP e por e-mail, e o ingest público do banner aceita 30 req/min por cliente e 600 req/min por site. Esses limites não emitem headers X-RateLimit-* — apenas o 429.

Limites de corpo (`413`)

Cada rota limita o tamanho do corpo antes de qualquer processamento:

Rotas	Limite
`POST /api/v1/public/consent` (ingest público, sem autenticação)	64 KiB
Rotas autenticadas em geral (sites, políticas, exports, webhooks, …)	1 MiB
Grupo `/api/v1/consents` — dimensionado para `POST /consents/batch` (até 1000 linhas)	8 MiB

Corpo com Content-Length acima do teto é rejeitado de imediato com 413 e código invalid_request. Corpos sem Content-Length (chunked) que estourem o teto durante a leitura podem aparecer como 400 de bind — trate ambos como “reduza o payload”. Esses tetos protegem o processo, não o negócio: limites por item (tamanho de campos, linhas do batch) são validados no DTO e retornam 400 com mensagem específica.

Dúvidas? suporte@consentfly.com.br

Introdução

Guias da API

Referência

Formato padrão

Códigos de erro

Status HTTP

CSRF (`403`)

Headers `X-RateLimit-*`

Limites de corpo (`413`)

​Formato padrão

​Códigos de erro

​Status HTTP

​CSRF (403)

​Headers X-RateLimit-*

​Limites de corpo (413)

Formato padrão

Códigos de erro

Status HTTP

CSRF (`403`)

Headers `X-RateLimit-*`

Limites de corpo (`413`)