# Exceções

Consolidamos aqui os erros mais comuns sujeitos a ocorrer em nossa API. Eles são categorizados de duas formas:

  • 4xx : Responsabilidade do Usuário
  • 5xx : Responsabilidade do Servidor

Em caso de exceção durante uma consulta que consome créditos, os mesmos serão estornados em até 2 minutos.


# 400 Bad Request

A consulta está mal formatada, refira-se ao vetor constraints para identificar a correção, exemplos:

{
  "code": 400,
  "message": "request validation failed",
  "constraints": [
    "taxId must be a numeric string that obeys digit verification algorithm"
  ]
}
{
  "code": 400,
  "message": "request validation failed",
  "constraints": [
    "each value in states must be one of the following values: BR, AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MG, MS, MT, PA, PB, PE, PI, PR, RJ, RN, RO, RR, RS, SC, SP, SE, TO",
    "states must be an array"
  ]
}
{
  "code": 400,
  "message": "request validation failed",
  "constraints": [
    "property maxAge should not exist when strategy is ONLINE"
  ]
}

# 401 Unauthorized

Uma forma de autenticação (chave de API, JWT ou assinatura) não foi fornecida ou é inválida:

{
  "code": 401,
  "message": "missing authorization"
}
{
  "code": 401,
  "message": "invalid authorization"
}

# 403 Forbidden

A autenticação fornecida é válida, todavia o usuário foi suspenso ou não tem acesso ao recurso:

{
  "code": 403,
  "message": "account has been suspended",
  "reason": "disposable e-mail"
}
{
  "code": 403,
  "message": "not enough privileges",
  "permission": "write:office"
}

# 404 Not Found

A rota ou recurso que buscou não existem:

{
  "code": 404,
  "message": "tax id not registered at revenue service"
}
{
  "code": 404,
  "message": "cached data unavailable"
}
{
  "code": 404,
  "message": "Cannot GET /cpf"
}

# 429 Too Many Requests

O usuário está sem créditos ou excedeu o limite de consultas por minuto:

{
  "code": 429,
  "message": "not enough credits",
  "required": 10,
  "remaining": 7
}
{
  "code": 429,
  "message": "rate limit exceeded"
}

# 500 Internal Server Error

Um erro inesperado ocorreu, nossa equipe será notificada para identificar e atuar no problema:

{
  "code": 500,
  "message": "unexpected error"
}

# 503 Service Unavailable

Um ou mais serviços estão indisponíveis no momento:

{
  "code": 503,
  "message": "rfb data fetching is offline"
}
Service Unavailable

# 504 Gateway Timeout

O serviço falhou em responder em tempo hábil:

{
  "code": 504,
  "message": "failed to fulfill request within timeout"
}