Erros
Falhas da Platform API usam códigos de status HTTP padrão. Quase toda falha
inclui uma string subcode estável sobre a qual os clientes devem decidir — os códigos de status
sozinhos são ambíguos (403 cobre scope, produto, origin, IP e tipo de chave).
Envelope
A maioria dos erros retorna um wrapper detail no estilo FastAPI:
{ "detail": "<subcode>" }
Payloads 429 estruturados (map_load_quota_exceeded, b2b_overloaded,
org_overloaded, tile_access_restricted) são objetos planos no nível
superior — sem wrapper detail:
{ "error": "map_load_quota_exceeded", "meter": "map_loads", "limit": 50000, "used": 50000 }
429s com string-detail (map-load hard stops) mantêm o wrapper:
{ "detail": "map_load_hard_stop" }
Alguns endpoints sem streaming relatam falhas como HTTP 200 com uma chave error —
principalmente POST /chat/control/route. Quem decide apenas pelo
status trata isso como sucesso. Sempre leia o body.
Tabela
| Status | Subcode | Significado | O que fazer |
|---|---|---|---|
| 401 | (no detail) | Chave ausente / inválida / revogada / expirada | Verifique o valor da chave e se ela não foi revogada. Viewer não precisa de chave. |
| 401 | publishable_requires_session | Uma chave publishable (kld_pk_…) foi enviada como bearer direto | Use-a pelo SDK, que a troca por uma sessão. |
| 403 | insufficient_scope | Chave válida, mas não possui o scope da rota | Crie / recrie uma chave com o scope correto (ai / maps / design). |
| 403 | tier_capability_not_allowed | A chave armazenada possuía a capacidade, mas o tier atual da organização não a permite mais (normalmente downgrade Pro→Free) | Faça upgrade do plano ou use um produto permitido pelo tier atual. |
| 403 | origin_required | Uma chave publishable foi usada sem Origin de navegador (ex.: server-side) | Chaves publishable são apenas para navegador. |
| 403 | session_origin_mismatch | O Origin da solicitação não está na allowlist da chave | Atualize os allowed origins da chave (consulte Obter uma chave de API). |
| 403 | product_not_allowed | A chave não é permitida para este produto | Crie uma chave com o produto permitido (ou use viewer, que não precisa de chave). |
| 403 | server_key_in_browser | Uma server key (kld_sk_…) foi usada em um navegador | Server keys são apenas para servidor; também são bloqueadas por CORS. |
| 403 | ip_not_allowed | Uma server key foi usada de um IP fora da sua allowlist | Atualize a IP allowlist da chave ou chame de um endereço permitido. |
| 403 | publishable_key_required | O SDK session exchange foi tentado com algo diferente de uma chave publishable | Use uma chave kld_pk_… na etapa de session-exchange. |
| 403 | sessions_disabled | A emissão de sessões está desativada para este deployment | Entre em contato com o suporte — é um estado operacional, não uma configuração do cliente. |
| 403 | sessions_not_configured | A infraestrutura de sessão não está configurada | Entre em contato com o suporte. |
| 422 | (various) | Body de solicitação malformado | Corrija o payload (consulte Endpoints). No mint, unknown_scope / unknown_product significam valor não reconhecido; publishable_live_requires_origins significa que uma chave publishable live foi criada sem allowed origins. |
| 429 | (flat) map_load_quota_exceeded | A franquia mensal de map-loads da organização foi esgotada | Faça upgrade ou reduza os carregamentos de mapa-base. |
| 429 | map_load_hard_stop | Organização paga está 5× acima da franquia de map-loads | O serviço para aqui; a faixa flexível acima da franquia continua funcionando até esse ponto. |
| 429 | (flat) tile_access_restricted | Solicitação Tile rejeitada (normalmente por falta do origin na allowlist). Inclui Retry-After: 3600 | Adicione o origin da página à allowlist da chave; tente novamente após o intervalo do header. |
| 429 | (flat) b2b_overloaded | O descarte global de solicitações está ativo | Reduza o ritmo e tente novamente com jitter. |
| 429 | (flat) org_overloaded | Descarte por organização | Reduza o ritmo e tente novamente. |
| 429 | limiter_unavailable | O rate limiter está temporariamente inacessível | Trate como transitório; tente novamente. |
| 429 | rate_limited | Solicitações demais neste momento | Respeite Retry-After. |
| 503 | (no detail) | Serviço de chaves temporariamente indisponível | Transitório — tente novamente em breve. |
Gerenciamento de chaves
Falhas de POST/PATCH/DELETE /shared-api/api-keys/* (Cognito org-admin
JWT, não uma platform key):
| Status | Subcode | Significado |
|---|---|---|
| 403 | free_plan_publishable_only | Organizações Free só podem criar chaves publishable. |
| 403 | plan_required | A organização não possui uma linha de plano API reconhecida. |
| 403 | tier_capability_not_allowed | Um PATCH tentou ampliar uma chave além do permitido pelo tier atual da organização. |
| 403 | vendor_scope_requires_acknowledgement | O scope vendor exige uma flag explícita de confirmação por chave. |
| 409 | key_limit_reached | A organização atingiu o limite de chaves por organização do seu plano. |
Consulte Obter uma chave de API para o fluxo completo de mint e o caminho de atualização PATCH.
Erros de streaming
Em um stream SSE, uma falha terminal chega como um evento error em vez de
status HTTP (a resposta já começou com 200):
event: error
data: { "type":"error", "message":"…", "code":"…", "partial_text":"…" }
Trate um evento error como o fim daquele stream. Um evento quota no meio do stream
não é um erro — é o medidor informando quanto orçamento
resta. Os clientes devem ignorar nomes de eventos desconhecidos — novos eventos podem ser
adicionados ao contrato estável sem mudança de versão.
CORS "bloqueado" no navegador
Se o navegador informar um bloqueio CORS em uma solicitação real, o Origin da solicitação
não está na allowlist da chave — não é uma falha de auth. Consulte
CORS & allowed origins.