Pular para conteúdo

Estrutura de Erros

Formato Padrão

Todos os erros da API Pontotel seguem um formato JSON consistente:

JSON
1
2
3
4
5
6
7
8
{
  "error": "validation_error",
  "message": "Dados inválidos na requisição",
  "details": {
    "email": ["Este campo é obrigatório."],
    "cpf": ["CPF inválido."]
  }
}
Campo Tipo Descrição
error string Código de erro (snake_case)
message string Mensagem legível para humanos
details object Detalhes por campo (quando aplicável)

Códigos de Status HTTP

Código Significado Quando ocorre
200 OK Requisição bem-sucedida
201 Created Recurso criado com sucesso
204 No Content Deleção bem-sucedida
400 Bad Request Dados inválidos ou regra de negócio
401 Unauthorized Token ausente, expirado ou inválido
403 Forbidden Sem permissão para o recurso
404 Not Found Recurso não encontrado
409 Conflict Conflito (ex: CPF duplicado)
429 Too Many Requests Rate limit excedido
500 Internal Server Error Erro interno no servidor
503 Service Unavailable Manutenção programada

Erros por Categoria

400 — Validação

JSON
1
2
3
4
5
6
7
8
{
  "error": "validation_error",
  "message": "Um ou mais campos são inválidos",
  "details": {
    "cpf": ["CPF inválido. Verifique o formato."],
    "data_admissao": ["Este campo é obrigatório."]
  }
}

401 — Autenticação

JSON
1
2
3
4
{
  "error": "authentication_failed",
  "message": "Token inválido ou expirado. Por favor, faça login novamente."
}

Solução: Realizar novo login e obter um novo access_token.

403 — Autorização

JSON
1
2
3
4
{
  "error": "permission_denied",
  "message": "Você não tem permissão para acessar este recurso."
}

Solução: Verificar se o usuário tem as permissões necessárias no portal Pontotel.

404 — Não Encontrado

JSON
1
2
3
4
{
  "error": "not_found",
  "message": "O recurso solicitado não foi encontrado."
}

409 — Conflito

JSON
1
2
3
4
5
6
7
{
  "error": "conflict",
  "message": "Já existe um empregado com este CPF neste empregador.",
  "details": {
    "cpf": ["CPF já cadastrado."]
  }
}

429 — Rate Limit

JSON
1
2
3
4
5
6
7
8
{
  "error": "rate_limit_exceeded",
  "message": "Você excedeu o limite de requisições",
  "limit": 500,
  "remaining": 0,
  "reset_at": "2025-02-09T15:00:00Z",
  "retry_after": 3600
}

Solução: Aguardar o valor em retry_after (segundos) antes de tentar novamente.

Tratamento em Código

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import requests

def fazer_requisicao(url, headers, payload=None):
    try:
        if payload:
            response = requests.post(url, json=payload, headers=headers)
        else:
            response = requests.get(url, headers=headers)

        if response.status_code == 401:
            # Token expirado — fazer login novamente
            raise TokenExpiredError("Refazer autenticação")

        elif response.status_code == 429:
            # Rate limit — aguardar
            retry_after = int(response.headers.get("Retry-After", 60))
            import time; time.sleep(retry_after)
            return fazer_requisicao(url, headers, payload)

        elif response.status_code >= 400:
            error = response.json()
            raise APIError(f"{error['error']}: {error['message']}")

        return response.json()

    except requests.exceptions.ConnectionError:
        raise APIError("Falha de conexão com a API")
JavaScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
async function fazerRequisicao(url, options = {}) {
  const response = await fetch(url, options);

  if (response.status === 401) {
    throw new Error('Token expirado — refazer autenticação');
  }

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    return fazerRequisicao(url, options);
  }

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.error}: ${error.message}`);
  }

  return response.json();
}

Próximos Passos