Status e Suporte

Diagnostique antes de escalar

Quase toda falha relatada é uma de cinco coisas, e cada uma tem uma assinatura distinguível:

Sintoma	Causa provável	Onde procurar
`401 unauthorized` em uma chamada que funcionava ontem	Chave rotacionada, desativada, ou o cabeçalho está ausente em um dos caminhos de código	Autenticação
`402 insufficient_balance`	Saldo abaixo da reserva para este envio	Conta e saldo
Uma única requisição retorna `200`, mas nada foi cobrado	O combo inteiro falhou; o status HTTP não é o desfecho	Cobrança e reembolsos
A mesma requisição ora tem sucesso, ora falha	Limitação de requisições, ou uma `Idempotency-Key` sendo reutilizada em payloads diferentes	Limites de requisições, Idempotência
Uma tarefa em lote fica em `processing` e `last_progress_at` para de avançar	Uma tarefa genuinamente travada, não apenas lenta	Status da tarefa

Vale dizer com clareza sobre o caso do last_progress_at: o tempo decorrido não é o sinal de falha, um timestamp estagnado é. Uma tarefa de 500,000 linhas pode legitimamente levar bastante tempo. Uma tarefa cujo last_progress_at não avançou é uma tarefa a escalar.

O que incluir em uma solicitação de suporte

Todos os campos abaixo são retornados pela API, o que significa que incluí-los não custa nada e economiza uma ida e volta:

Inclua	De onde vem
`request_id`	Toda resposta de tempo real, incluindo falhas que retornaram um corpo
`task_id`	Todo envio em lote e toda resposta de status da tarefa
`api_key_id`	`GET /v1/api-key` — identifica a chave sem expô-la
O status HTTP e o corpo da resposta exatos	Seus próprios logs; em particular o campo `code`
Um timestamp UTC com segundos	Seus próprios logs
A requisição que você enviou, com a chave ocultada	Seu próprio código

Nunca cole uma chave de API em uma solicitação de suporte. api_key_id identifica a chave, e a chave em si dá acesso ao seu saldo.

Comunicação de incidentes

Avisos no nível da conta — manutenção planejada, capacidade degradada — aparecem no Console, que também é onde ficam o saldo e os registros. A API expõe essas mesmas condições diretamente à sua integração, como códigos de erro em vez de texto corrido:

Código	O que significa para uma integração em execução
`detection_capacity_unavailable`	Sem capacidade no momento. Faça backoff e tente novamente; nada foi cobrado.
`realtime_route_unavailable`	Nenhuma rota de tempo real disponível. Faça backoff e tente novamente.
`realtime_rate_limiter_unavailable`	O próprio limitador está fora do ar, então a admissão não pode ser decidida. Tente novamente mais tarde.
`realtime_fact_cache_unavailable`	Uma dependência de tempo real está fora do ar. Tente novamente mais tarde.

Estes são 503s e todos estão no grupo “aguarde e tente novamente” — consulte Códigos de erro para o agrupamento completo, incluindo quais falhas são seguras para repetir com a mesma Idempotency-Key.

Onde a plataforma está hoje

Dois fatos operacionais são verificáveis de fora e vale a pena conhecê-los antes de abrir um incidente:

A API é servida por trás da Cloudflare, então o caminho de rede e a terminação de TLS são operados pela Cloudflare, e não em um único host de origem.
Toda resposta carrega X-RateLimit-Remaining, então um cliente que registra cabeçalhos de resposta consegue distinguir “limitado pelo meu próprio limite” de “o serviço está fora do ar” sem perguntar a ninguém. Os grupos geral e de detecção também carregam X-RateLimit-Limit em toda resposta; o de tempo real não, porque ele gasta um token bucket em vez de um teto fixo por minuto.

A seguir

Códigos de erro — os grupos de novas tentativas, que é a tabela de triagem mais rápida
Segurança — como lidar com a chave, como rotacioná-la e o que nunca enviar