Manejo de errores

Todas las respuestas de error de APIs Perú comparten un mismo formato JSON consistente, sin importar el endpoint o el código HTTP.

Formato de respuesta

{
  "ok": false,
  "error": "Descripción legible del problema",
  "status": 4XX
}

Códigos HTTP

Código Nombre Descripción
400 Bad Request Parámetros faltantes o inválidos (formato, longitud).
401 Unauthorized API key ausente, mal formada o revocada.
403 Forbidden Origin o IP bloqueado según las restricciones de tu key.
404 Not Found Recurso o registro no encontrado en la fuente oficial.
429 Too Many Requests Rate limit excedido. Reintenta tras el Retry-After.
500 Internal Server Error Error inesperado del servicio. Reintenta con backoff.
502 Bad Gateway Fuente upstream (SUNAT, RENIEC) no disponible.

Ejemplos por código

400 — Input inválido

{
  "ok": false,
  "error": "El parámetro 'numero' debe tener 11 dígitos.",
  "status": 400
}

401 — Sin autenticación

{
  "ok": false,
  "error": "API key ausente o inválida.",
  "status": 401
}

403 — Origen bloqueado

{
  "ok": false,
  "error": "Origin no autorizado para esta API key.",
  "status": 403
}

404 — No encontrado

{
  "ok": false,
  "error": "RUC no encontrado en SUNAT.",
  "status": 404
}

429 — Rate limit

{
  "ok": false,
  "error": "Rate limit excedido. Reintenta en 47 segundos.",
  "status": 429
}

500 / 502 — Error de servicio

{
  "ok": false,
  "error": "Fuente upstream no disponible temporalmente.",
  "status": 502
}