Operação da integração · v1 em prévia

Trate o código, preserve o contexto.

Os erros têm um envelope consistente. Use error.code na lógica da integração; a mensagem pode mudar.

Envelope

JSON

{
  "error": {
    "code": "unauthenticated",
    "message": "Credencial ausente, inválida ou revogada."
  },
  "version": "v1"
}

HTTP	Código	Como tratar
401	unauthenticated	Confira a credencial e se ela foi revogada. Não repita indefinidamente.
403	forbidden_scope	Solicite o escopo necessário para o recurso.
400	invalid_cursor	Confira o cursor recebido da resposta anterior.
400	invalid_limit	Use um inteiro de 1 a 100.
429	rate_limited	Respeite o Retry-After em segundos antes de tentar de novo.
503	unavailable	Aguarde e tente novamente com intervalo progressivo.
404	unknown_resource	Confira o endereço e a versão do recurso.

Situação	Conduta da integração
400, 401, 403 ou 404	Corrija parâmetro, credencial, escopo ou rota antes de repetir.
429	Aguarde Retry-After e coordene os processos da mesma credencial.
503 ou falha temporária de rede	Use espera progressiva, teto de tentativas e possibilidade de interromper.
Resposta inesperada	Interrompa a interpretação dos dados e registre contexto sem segredos.

Registre a rota, o horário, o status e o código para diagnóstico.
Não registre o cabeçalho Authorization nem a credencial.
Limite o número de tentativas e evite repetir erros de autenticação sem corrigir a causa.

Referência conferida em 23 de setembro de 2026. Relatar uma dúvida na documentação.