Pular para conteúdo

Tratamento de erros

A API GOB tem um comportamento de erro previsível e enxuto: o resultado é comunicado por meio do status HTTP e de um cabeçalho explicativo — não por um corpo JSON de erro.

Sem JSON no corpo em caso de erro

Não será retornado JSON no corpo em caso de erro. Será retornado o status code HTTP apropriado (200, 400, 401, 403, 404, 500), e um cabeçalho adicional X-Status-Reason explicará o motivo.

Códigos de status

Código Resposta Significado
200 OK Sucesso.
400 Bad Request Parâmetro inválido ou requisição malformada.
401 Unauthorized Chave de API ausente ou inválida.
403 Forbidden Permissão negada.
404 Not Found Recurso não encontrado.
500 Internal Server Error Erro interno no servidor.

O cabeçalho X-Status-Reason

Sempre que ocorrer um erro, a resposta inclui o cabeçalho X-Status-Reason com o motivo. Inspecione-o para diagnosticar a falha:

curl -i -H "X-Api-Key: CHAVE_INVALIDA" \
  "https://integracao.gob.com.br/api/v1/Account"
# HTTP/1.1 401 Unauthorized
# X-Status-Reason: ...

curl.exe -i -H "X-Api-Key: CHAVE_INVALIDA" `
  "https://integracao.gob.com.br/api/v1/Account"
# HTTP/1.1 401 Unauthorized
# X-Status-Reason: ...

const res = await fetch(url, { headers: { "X-Api-Key": key } });
if (!res.ok) {
  const motivo = res.headers.get("X-Status-Reason");
  throw new Error(`Falha ${res.status}: ${motivo}`);
}

Checklist de diagnóstico

  • O cabeçalho X-Api-Key está presente e correto? → evita 401.
  • O nome da entidade existe? Veja Entidades. → evita 404.
  • O searchParams é um JSON válido e codificado com encodeURIComponent? → evita 400.
  • O nome da relação está em camelCase? → evita 400 / 404.
  • A sua chave tem permissão para o recurso? → evita 403.