Erros

As respostas públicas seguem Problem Details com title, status, detail e, quando houver, code, suggestion e request_id.

Status	Quando aparece	Ação imediata
401	sk_* ausente, inválida ou fora do ambiente	Revise segredo e host
409	Reuso incorreto de Idempotency-Key	Compare o payload e decida se era replay legítimo
422	Validação de schema ou regra de negócio	Corrija o campo e não faça retry cego
429	Burst acima do limite	Backoff exponencial com jitter
502	Dependência externa indisponível	Retry controlado e observabilidade

Códigos do gateway

landing_proxy_untrusted

403. A origem do pré-cadastro não foi reconhecida como o formulário oficial. Não repita a chamada diretamente; reinicie o fluxo pela página pública.

influencer_gateway_unavailable

503. O canal de pré-cadastro está temporariamente indisponível. Tente novamente com backoff e preserve o request_id.

idempotency_key_required

400. A operação mutável exige Idempotency-Key. Gere um UUID v4 por intenção de negócio e reutilize-o apenas no retry da mesma operação.

api_key_missing

401. Nenhuma API key foi enviada. Use Authorization: Bearer sk_... no backend ou X-API-Key quando o cliente HTTP exigir esse formato.

api_key_invalid

401. A chave não existe, foi revogada ou pertence a outro ambiente. Confira o prefixo, o host e a rotação ativa no dashboard.

api_key_auth_unavailable

503. A validação da chave não respondeu. Faça retry controlado; se persistir, envie o request_id ao suporte sem compartilhar o segredo.

scope_forbidden

403. A chave é válida, mas não possui o escopo da rota. Ajuste os escopos ou use outra chave de menor privilégio que cubra a operação. No navegador, use uma chave publishable somente nas rotas explicitamente compatíveis; nunca exponha uma chave secreta.

checkout_origin_required

403. A chamada pública de checkout não trouxe uma origem de navegador válida. Abra o checkout pelo domínio hospedado ou pelo domínio personalizado configurado. Em renderização no servidor, preserve o host público encaminhado; não invente nem sobrescreva o header Origin.

rate_limit_exceeded

429. A chave excedeu o limite de requisições. Respeite Retry-After quando presente e aplique backoff exponencial com jitter.

idempotency_key_replayed

409. A mesma chave já foi reservada para esse endpoint. Recupere a resposta original para o mesmo payload ou gere outra chave para uma nova intenção.

Regra prática

Não trate erro por texto livre. Roteie por status, code e request_id.