Códigos de erro

Todo erro da API tem um código error estável. Ramifique por error para um tratamento preciso, ramifique por type para grupos grossos e sempre registre request_id quando ele estiver presente, para que o suporte possa rastrear a chamada.

Envelopes de erro

Os endpoints do protocolo OAuth seguem erros no estilo da RFC 6749:

{
 "error": "invalid_request",
 "error_description": "code_challenge_method is required and must be S256"
}

Os erros da API de dados para desenvolvedores mantêm o mesmo campo plano error e podem adicionar um type grosso mais um request_id rastreável:

{
 "error": "insufficient_scope",
 "scope": "recipe:publish",
 "type": "auth_error",
 "request_id": "req_..."
}

A validação de esquema roda antes de qualquer handler. Um corpo ou formulário que não cumpre o esquema OpenAPI é respondido com validation_error e um array details que nomeia cada campo problemático; esse envelope não traz type, error_description nem request_id, e o código que o handler devolveria nunca chega a aparecer: um grant_type desconhecido em POST /oauth/token sai como validation_error, não como unsupported_grant_type, e um POST /oauth/register sem redirect_uris como validation_error, não como invalid_request.

{
 "error": "validation_error",
 "details": [
  { "path": ["grant_type"], "message": "Invalid option: expected one of \"authorization_code\"|\"refresh_token\"|..." }
 ]
}

As respostas de limite de taxa incluem tempos de nova tentativa acionáveis por máquina:

{
 "error": "rate_limited",
 "retry_after_ms": 1200,
 "next_request_at": "2026-06-17T12:00:01Z",
 "hint": "Rate limited. Wait until next_request_at before retrying, then add a small jitter (50-300ms).",
 "agent_instruction": "sleep_until_next_request_at"
}

Tipos de erro

Códigos comuns

A coluna Tipo é o campo type que a resposta realmente traz. Os corpos do protocolo OAuth (OAuthProtocolError) e os anteriores ao handler (validation_error, unauthorized) não o têm, por isso suas linhas mostram um traço.

Cabeçalhos a registrar

Manuais de diagnóstico

invalid_token

Verifique se o cabeçalho é exatamente Authorization: Bearer <access_token>. Se o token expirou ou foi revogado, renove-o ou passe o usuário pelo consentimento novamente. Mantenha as credenciais de teste e de produção separadas; um cliente de teste devolve dados do ambiente de testes.

insufficient_scope

Leia o campo scope no corpo do erro. Solicite esse escopo para o cliente, obtenha um consentimento novo e tente novamente com o novo token.

invalid_request do PKCE

O PKCE é obrigatório e apenas S256. Inclua code_challenge, defina code_challenge_method como S256 e nunca use plain.

rate_limited

Aguarde até next_request_at ou até o cabeçalho Retry-After e depois tente novamente com um pequeno jitter. Não faça polling em um laço apertado.

quota_exceeded

A cota de publicação é separada dos limites de taxa de leitura. Rebaixamentos suaves incluem X-Quota-Restored-At; rebaixamentos rígidos não se restauram automaticamente e exigem mudanças de comportamento ou revisão.

Erros de idempotência

Use uma Idempotency-Key por operação lógica de publicação. Reutilizar a mesma chave com o mesmo corpo reproduz o resultado com segurança; reutilizá-la com um corpo diferente devolve idempotency_key_reuse.

validation_error

A requisição nunca chegou ao handler: leia details[].path, corrija cada campo conforme o esquema OpenAPI e tente de novo. Só um corpo que valida pode produzir os códigos próprios do endpoint (unsupported_grant_type, invalid_scope, invalid_redirect_uri, …): corpos RFC 6749 com error mais um error_description opcional, também sem type nem request_id.

Relacionado

• Primitivas de consistência — o envelope de erro, a paginação, a idempotência e as convenções de limite de taxa
• Explorador de API — veja esses corpos e cabeçalhos ao vivo
• Visão geral da API — a superfície de endpoints e os links do OpenAPI