Skip to main content

​
Formato de erro

Todos os erros da API GYRA+ seguem o mesmo formato: 
{
  "statusCode": 400,
  "message": "Credenciais inválidas.",
  "error": "Bad Request"
}
CampoTipoDescrição
statusCodenumberCódigo HTTP do erro
messagestringMensagem descritiva em português
errorstringCategoria do erro HTTP

​
Erros de autenticação (4xx)

​
400 — Bad Request

MensagemCausaSolução
"Credenciais inválidas."gyra-client-id ou gyra-client-secret incorretosVerifique as credenciais no painel do Toolbox
"Documento inválido."CPF ou CNPJ com formato ou dígitos incorretosValide o documento antes de enviar (sem formatação)
"Tipo de documento inválido."Campo type diferente de CPF ou CNPJUse exatamente "CPF" ou "CNPJ" (maiúsculo)
"policyId inválido."ID de política inexistente ou inativoConsulte as políticas ativas com GET /credit-policy/policy

​
401 — Unauthorized

MensagemCausaSolução
"Token de acesso inválido."Token JWT ausente, malformado ou expiradoReautentique com POST /auth/authenticate
"Token expirado."JWT com mais de 24 horasGere um novo token

​
403 — Forbidden

MensagemCausaSolução
"Você não tem permissão para acessar este recurso."Organização sem acesso ao endpointEntre em contato com atendimento@gyramais.com
"Plano sem permissão para este tipo de relatório."Tipo de relatório não incluído no plano contratadoVerifique o plano ou contate o comercial

​
404 — Not Found

MensagemCausaSolução
"Registro não encontrado."reportId, sectionId ou webhookId inexistenteVerifique se o ID está correto
"Política não encontrada."policyId inválido ou removidoConsulte políticas ativas

​
429 — Too Many Requests

MensagemCausaSolução
"Limite de requisições excedido."Rate limit atingidoAguarde antes de tentar novamente. Implemente backoff exponencial

​
Erros de servidor (5xx)

​
500 — Internal Server Error

Erro inesperado no servidor. Se persistir, entre em contato com atendimento@gyramais.com informando o reportId ou a requisição que falhou.

​
503 — Service Unavailable

O serviço está temporariamente indisponível. Implemente retry com backoff. Acompanhe o status em status.gyramais.com.br.

​
Erros em seções do relatório (sections[].errors)

Algumas integrações podem falhar durante o processamento do relatório. Esses erros ficam na array errors da seção correspondente: 
{
  "type": { "value": "PROCESSES" },
  "errors": [
    {
      "integrationId": "64a3...",
      "integrationType": "LAWSUITS",
      "message": "Timeout na consulta ao provedor externo",
      "code": "INTEGRATION_TIMEOUT",
      "occurredAt": "2025-03-01T10:31:00.000Z"
    }
  ],
  "details": { ... }  // Dados parciais disponíveis
}
CódigoCausa
INTEGRATION_TIMEOUTProvedor externo não respondeu no prazo
INTEGRATION_UNAVAILABLEProvedor externo indisponível temporariamente
INTEGRATION_NO_DATANenhum dado encontrado para o documento neste provedor
INTEGRATION_INVALID_DOCUMENTDocumento inválido para este provedor específico
Erros em integrações individuais não invalidam o relatório. Os dados disponíveis são normalizados normalmente. A decisão da política é tomada com base nos dados que chegaram.

​
Boas práticas para tratamento de erros

Para erros 429 e 503, não tente novamente imediatamente. Use backoff: 1s, 2s, 4s, 8s… até um máximo de 60s.
Erros 4xx são da sua aplicação — não tente novamente automaticamente. Corrija o payload. Erros 5xx são do servidor — faça retry.
Ao abrir chamado de suporte, o reportId é essencial para diagnóstico. Guarde em seus logs.
Valide CPF e CNPJ (dígitos verificadores) no seu sistema antes de chamar a API. Isso evita erros 400 desnecessários.