Códigos HTTP
A API usa códigos de status HTTP convencionais. Abaixo, todos os códigos que
aparecem nos endpoints públicos, com o significado e onde cada um é emitido.
O corpo dos erros segue o
envelope de erro, com um error.code estável.
Sucesso · 2xx
| Código | Significado | Onde aparece |
|---|---|---|
| 200 | OK. Requisição bem-sucedida; o corpo traz o envelope
{ success, data, meta? } (ou o formato legado,
nos endpoints de anúncios). | Todos os endpoints públicos em caso de sucesso. |
Erros do cliente · 4xx
| Código | Significado | Onde aparece |
|---|---|---|
| 400 | Bad Request. Requisição inválida: parâmetro fora do
formato, corpo malformado ou regra de validação não atendida (error.code: VALIDATION_ERROR). | Busca (q < 3 caracteres), entrega de anúncio (formato
inválido, slots inválidos), clique (clickToken inválido/expirado)
e parâmetros de paginação inválidos. |
| 401 | Unauthorized. Chave de API ausente ou inválida no header
X-API-Key. | Todos os endpoints públicos (todos exigem chave). |
| 403 | Forbidden. Chave válida, mas sem permissão para a ação
(error.code: FORBIDDEN). | Principalmente no clique de anúncio, quando Origin/Referer não corresponde ao domínio configurado do blog. |
| 404 | Not Found. Recurso inexistente ou não publicado para o identificador informado. | Post por ID/slug, categoria por ID, tag por ID e listagens por categoria/tag inexistente. |
| 405 | Method Not Allowed. Verbo HTTP não suportado neste path.
O header Allow lista os métodos aceitos. | Qualquer path público chamado com um verbo não suportado (ex.: DELETE /public/posts). |
| 409 | Conflict. O clickToken já foi utilizado
(uso único). | Apenas no clique de anúncio (POST /public/ads/tracking/click). |
| 415 | Unsupported Media Type. O Content-Type da requisição não é application/json em rota que exige
JSON. | Requisições com corpo: POST /public/ads/formats e os endpoints
de tracking. |
| 429 | Too Many Requests. Limite de requisições excedido. O
header Retry-After (segundos) indica quando tentar de novo. | Qualquer endpoint público sob carga excessiva. Veja Rate limits. |
Erros do servidor · 5xx
| Código | Significado | Onde aparece |
|---|---|---|
| 500 | Internal Server Error. Falha inesperada no servidor
(error.code: INTERNAL_ERROR). | Qualquer endpoint. Transitório: trate com retentativa e backoff. |