Erros, limites e novas tentativas

API Os clientes devem tomar decisões com base nos códigos de status HTTP, nos códigos de erro estáveis e nos cabeçalhos de resposta. Não codifique valores de cota por nome de plano: os limites do gateway e do serviço são determinados pelo plano ativo, pela configuração do administrador, pelo perfil e pela política atual do produto.

Envelope de erro

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key does not have the required scope.",
    "status": 403
  }
}

Alguns serviços proxy podem retornar um envelope específico do serviço. Sempre preserve o status HTTP e o corpo da resposta em logs de diagnóstico estruturados, mas oculte as credenciais e os dados confidenciais do usuário.

Estados comuns

Status	Significado	Ação do cliente
400	Formato ou parâmetro inválido da solicitação	Corrija a solicitação; não repita a tentativa sem alterações.
401	Credencial ausente, inválida, vencida ou revogada	Substitua ou renove a credencial.
403	A operação foi negada devido a políticas de escopo, serviço, função, plano, cota, IP ou recurso	Verifique o código de erro e a configuração atual da conta.
404	A rota ou o recurso solicitado não foi encontrado	Verifique a versãoAPI, o caminho, o identificador e a visibilidade do recurso.
409	A operação entra em conflito com o estado atual do recurso	Atualize o estado antes de decidir se deve tentar novamente.
429	Foi atingido um limite de solicitações por minuto ou diário	Aguarde Retry-After; reduza a simultaneidade ou a frequência de polling.
500	A solicitação chegou a um serviço que falhou inesperadamente	Tente novamente somente se for seguro repetir a operação.
502, 503, 504	Uma dependência, um controle ou um serviço estava temporariamente indisponível	Aplique recuo exponencial limitado com jitter.

Os códigos de erro do gateway podem incluir MISSING_API_KEY, INVALID_API_KEY, IP_NOT_ALLOWED, INSUFFICIENT_SCOPE, RATE_LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED, RATE_LIMIT_UNAVAILABLE, NOT_FOUND, SERVICE_UNAVAILABLE, e INTERNAL_ERROR. Os serviços de destino podem retornar códigos adicionais para seus próprios recursos e cotas.

Cabeçalhos de limite ativos

As solicitações autenticadas bem-sucedidas e rejeitadas podem incluir:

X-RateLimit-Limit: <current minute limit>
X-RateLimit-Remaining: <requests left in the current minute window>
X-RateLimit-Reset: <Unix timestamp>
X-DailyLimit-Limit: <current daily limit>
X-DailyLimit-Remaining: <requests left in the current daily window>
Retry-After: <seconds>

Leia esses valores em tempo de execução. Os limites podem variar de acordo com o plano, a conta, o perfil, a política do administrador e o estágio de lançamento, e podem ser alterados sem a necessidade de um lançamento do cliente.

Estratégia de repetição

Utilize o backoff exponencial limitado com jitter para status transitórios. Uma sequência prática começa em torno de um segundo e aumenta até um atraso máximo moderado. Respeite um valor maior Retry-After valor, quando houver um.

Refaça a tentativa somente quando a operação for segura:

• GET Normalmente, é seguro repetir as solicitações.
• Uma operação de criação, envio ou atualização com falha pode ter sido concluída antes que a conexão falhasse. Confirme o estado do recurso antes de repeti-la.
• Não repita a tentativa 400, 401, ou a maioria 403 respostas sem alterar a solicitação ou a credencial.
• Defina um número máximo de tentativas e exiba uma mensagem de erro útil quando esse limite for atingido.

Reduza o tráfego desnecessário

• Armazene em cache respostas de direitos de acesso somente leitura ou de metadados por um curto período apropriado, em vez de verificá-las a cada interação com a interface do usuário.
• Preferir webhooks para eventos suportados.
• Agrupe solicitações idênticas provenientes da mesma carga de trabalho.
• Pagine coleções grandes e evite concorrência ilimitada.
• Utilize o CLI’s --json Gere a saída em scripts, em vez de emitirAPI solicitações duplicadas para formatação.

Diagnosticar uma recusa inesperada

1. Chamada GET /v1/auth/whoami para confirmar a identidade e a chave ativas.
2. Chamada GET /v1/auth/quota para obter o instantâneo atual da cota do Gateway.
3. Confirme se a chave possui o escopo exigido pela rota.
4. Confirme se o serviço de destino está habilitado para o perfil ativo.
5. Verifique as permissões de função e organização no serviço de destino.
6. Registre o status, o código de erro, os cabeçalhos de resposta e a hora da solicitação antes de entrar em contato com CHAMPREP Suporte.