Erros estruturados#
Falhas usam application/problem+json com type, title, status, code, detail e request_id. Use code para decisões de integração e request_id para suporte. Não dependa da redação de title ou detail. Uma resposta HTTP não bem-sucedida deve ser tratada antes de ler campos de sucesso.
O que cada status indica#
- 400: parâmetro, schema ou cursor inválido. Corrija a entrada antes de reenviar.
- 401: credencial ausente, inválida ou revogada.
- 403: acesso/origem não autorizado. Confira seu canal; não tente fornecer secrets internos.
- 404: identificador não encontrado no catálogo.
- 429: quota ou limite de requisições. Respeite Retry-After e consulte seu plano.
- 500 ou 503: falha interna ou indisponibilidade temporária. Use retry limitado e suporte se persistir.
Retries sem amplificar falhas#
Configure timeouts, número máximo de tentativas e backoff com jitter. Respeite o Retry-After retornado e não continue uma sequência agressiva quando a quota mensal estiver esgotada. Requests autenticados podem contabilizar consumo mesmo se a resposta for um erro; os limites dependem do canal e do plano.