Estructura de errores¶

Formato estándar¶

Todos los errores de la API Puntotel sigue un formato JSON consistente:

JSON
{
  "error": "validation_error",
  "message": "Dados inválidos na requisição",
  "details": {
    "email": ["Este campo é obrigatório."],
    "cpf": ["CPF inválido."]
  }
}

Campo	Tipo	Descripción
`error`	string	Código de error (snake case)
`message`	string	Mensaje legible para humanos
`details`	object	Detalles por campo (cuando proceda)

Códigos de estado HTTP¶

Código	Significado	Cuando ocurre
`200`	Aceptar	Requisición exitosa
`201`	Created	Recurso creado con éxito
`204`	No Content	Succión exitosa
`400`	Bad Request	Datos no válidos o regla de negocio
`401`	Unauthorized	Token ausente, espirado o inválido
`403`	Forbidden	Sin permiso para el recurso
`404`	Not Found	Recurso no encontrado
`409`	Conflict	Conflicto (ex: CPF duplicado)
`429`	Too Many Requests	Rate limit excedido
`500`	Internal Server Error	Error interno en el servidor
`503`	Servicio Unavailable	Mantenimiento programado

Errores por categoría¶

400 — Validación¶

JSON
{
  "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 — Autenticación¶

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

Solución: Realizar nuevo inicio de sesión y obtener un nuevo access_token.

403 — Autorización¶

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

Solución: Comprobar si el usuario tiene los permisos necesarios en el portal Pontotel.

404 — No encontrado¶

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

409 — Conflicto¶

JSON
{
  "error": "conflict",
  "message": "Já existe um empregado com este CPF neste empregador.",
  "details": {
    "cpf": ["CPF já cadastrado."]
  }
}

429 — Rate Limit¶

JSON
{
  "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
}

Solución: Esperar el valor en retry_after (segundos) antes de volver a intentarlo.

Tratamiento en código¶

PythonJavaScript

Python
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
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();
}