Erros e diagnóstico

Existem duas famílias de erro, em dois lugares diferentes:

• Administração (a API que a Console usa): envelope com code estável, reason curto e message humana.
• Tráfego (a API publicada): status HTTP do gateway ou do seu backend; o corpo pode vir do gateway, do componente de autenticação ou do seu próprio serviço.

Envelope de erro da administração

{
  "error": {
    "code": "route_conflict",
    "reason": "duplicate_path_and_method",
    "message": "Já existe rota com o mesmo caminho normalizado e método.",
    "retryable": false,
    "request_id": "0192f3a4-4444-7000-8000-000000000004",
    "correlation_id": "0192f3a4-4444-7000-8000-000000000004",
    "details": {"conflicting_route_id": "0192f3a4-5555-7000-8000-000000000005"}
  }
}

• code é o contrato (nunca muda); message pode melhorar; reason é o detalhe curto e estável.
• retryable: true aparece em erros 5xx, em idempotency_key_in_progress e em too_many_requests.
• Nenhum código carrega detalhe criptográfico: falha de credencial vira unauthorized com razão curta, e o motivo técnico fica só no log.

Código, causa e ação

code	HTTP	Causa	Ação
not_found	404	recurso inexistente ou de outra organização	confira o id; se for de outra organização, o 404 é intencional
unauthorized	401	credencial ausente, expirada, assinatura inválida, iss/aud errados	renove o token na Console; confira o emissor configurado
scope_required	403	o token não tem a permissão da operação	peça a permissão correspondente
validation_error	400	corpo, caminho ou parâmetro inválido	leia o reason e corrija o valor
backend_not_allowed	400	destino recusado pela política (IP literal, faixa privada, sufixo interno, timeout de DNS, mixed_destinations)	use host público que resolva só para IP público
cors_insecure	400	origem http://, com caminho, com credencial, ou * com allow_credentials	use https://host[:porta]
invalid_cursor	400	cursor de paginação adulterado ou de outra consulta	refaça a listagem do começo
method_not_allowed	405	método HTTP não suportado no recurso	confira o método
route_conflict	409	já existe rota com o mesmo caminho normalizado e método	renomeie o caminho ou remova a rota antiga
api_published	409	tentou excluir API publicada ou ativa	desative antes de excluir
tenant_suspended	409	organização suspensa: escrita bloqueada	regularize a organização com o time comercial ou de suporte
operation_in_progress	409	já existe operação não terminal para a API	aguarde e repita depois
idempotency_key_in_progress	409	requisição com a mesma Idempotency-Key ainda em execução	aguarde e repita a mesma requisição
conflict	409	conflito de unicidade ou integridade (inclusive api_not_disabled)	veja o reason
precondition_failed	412	If-Match diverge do draft_version atual	releia o recurso e refaça a alteração
idempotency_key_reused	422	mesma Idempotency-Key com corpo diferente	use uma chave nova por operação
runtime_unavailable	503	o runtime não está disponível para aplicar mudanças	repita; se persistir, abra incidente
publish_validation_failed	422	a configuração não pode ser publicada	leia details.problems
revision_not_found	404	revisão não existe ou não é daquela API	liste as revisões da API
nothing_to_publish	409	o rascunho é igual à revisão publicada (ou reversão para a já ativa)	nada a fazer
api_disabled	409	a operação exige API habilitada	reative antes
api_not_published	409	a operação exige API publicada e ativa (hoje: a ferramenta de teste)	publique antes
consumer_name_taken	409	já existe consumidor com esse nome na organização	escolha outro nome
credential_limit_reached	409	limite de chaves ativas por consumidor	revogue uma antes de emitir outra
domain_taken	409	hostname já verificado por outra organização	use outro nome ou fale com o dono atual
hostname_in_use_by_api	409	o hostname é o endereço padrão de uma API	use outro nome
domain_not_allowed	400	FQDN inválido, com curinga ou sob zona reservada	corrija o nome
domain_verification_pending	409	a posse ainda não foi verificada	publique o TXT e verifique
invalid_openapi	422	documento que não é OpenAPI ou Swagger válido	valide o documento antes de enviar
payload_too_large	413	corpo acima de 1 MiB	reduza o corpo
too_many_requests	429	validações ou imports simultâneos demais na organização	aguarde e repita
internal_error	500	erro interno	repita; se persistir, abra incidente com o request_id

Motivos (reason) que valem conhecer

O code é estável e agrupa; o reason diz qual validação falhou.

code	reason	Significado
validation_error	window_too_large	janela de uso acima do teto da granularidade (3, 90 ou 400 dias)
	invalid_window	from não é anterior a to
	invalid_timestamp, invalid_since	timestamp fora do ISO-8601
	since_in_future	since de logs no futuro
	granularity_invalid	não é minute, hour ou day
	priority_out_of_range	priority fora de 0..1000
	timeout_override_out_of_range	timeout_override_ms fora de 1000..300000
	rate_limit_override_incomplete	rate_limit_override sem limit ou sem window_seconds
	timeout_override_conflict, rate_limit_override_conflict	mandou o valor e o clear_* correspondente
invalid_openapi	yaml_aliases_exceeded, yaml_depth_exceeded, yaml_expansion_exceeded, yaml_recursive_alias	documento YAML hostil
	parse_timeout	o parse passou do prazo
too_many_requests	openapi_parser_busy	imports simultâneos demais
	backend_validation_busy	validações de destino com DNS simultâneas demais
	api_test_rate_limited	ferramenta de teste: 30 chamadas por minuto por organização
conflict	certificate_in_use	certificado vivo do mesmo hostname pertence a outro sujeito
	api_not_disabled	reativação numa API que não está desativada
not_found	credential_not_found	credential_id da ferramenta de teste não existe, não está ativo ou expirou

Tráfego: erros do gateway

Status	Corpo típico	Causa	Ação
401	corpo do componente de chave ou {"error":"invalid_token"}	chave ausente, inválida ou revogada; chave no cabeçalho que a política não escolheu; token inválido	confira x-api-key ou Ocp-Apim-Subscription-Key; no modo JWT, confira iss, aud, exp e nbf
403	vazio	consumidor não autorizado naquela API	autorize o consumidor na API
403	{"error":"insufficient_scope"}	token sem os escopos exigidos	emita um token com o escopo
403	{"error":"api_suspended"}	organização suspensa	contate o suporte
404	{"error":"not_found"}	host desconhecido ou rota inexistente no gateway	confira o endereço e o caminho publicados
429	mensagem rate_limited	limite de taxa excedido	reduza a taxa ou peça revisão do limite
413	—	corpo maior que o limite da API	ajuste o limite ou reduza o corpo
502, 503, 504	—	o backend não respondeu, respondeu inválido ou estourou o tempo	verifique o backend e os timeouts
408	—	o cliente demorou a enviar a requisição	ajuste o cliente
falha de TLS	—	SNI desconhecido (não há certificado padrão)	use um endereço cadastrado e ativo

Diagnóstico rápido por sintoma

Sintoma	Primeiro suspeito	Como confirmar
"a API não responde"	não foi publicada, ou o endereço não aponta para o gateway	status da API; GET /__nn/ping
"responde 404 em tudo"	o Host ou SNI não é um endereço da API	confira default_hostname e os domínios ACTIVE
"responde 401 e minha chave está certa"	consumidor suspenso, chave revogada, ou chave na URL	liste as credenciais e confira o cabeçalho
"responde 403"	falta autorização na API (não é erro de chave)	liste os consumidores autorizados na API
"publiquei e nada mudou"	has_unpublished_changes = false (nada a publicar) ou operação FAILED	operações da API
"meu domínio está em ERROR"	TXT ausente por 7 dias, ou certificado a menos de 7 dias de expirar	state, last_error e o roteamento
"erro 409 domain_taken com um domínio que é meu"	outro cadastro (talvez antigo, seu) ainda não removido	verifique domínios antigos e remova
"a latência subiu e o limite parou de valer"	armazenamento de contadores fora	ver Políticas de tráfego e limites

Como pedir ajuda com dados úteis

Envie: o X-Request-Id da resposta (ou o correlation_id), o horário com fuso, o endpoint, o code e o reason e — se for tráfego — o endereço da API, o método, o caminho e o status. Sem isso, a investigação começa do zero.

Próximos passos

• Logs de acesso: a linha a linha da requisição.
• Uso e métricas: totais, p95 e saúde do backend.
• Publicação: os códigos de falha de uma operação.