Errores

Formato base

Los errores públicos usan application/problem+json.

{
  "type": "https://chequea.pe/errors/validation",
  "title": "Validacion fallida",
  "status": 400,
  "detail": "El RUC debe tener 11 digitos",
  "instance": "/api/v1/ruc/123"
}

Códigos comunes

400

La solicitud llegó, pero tiene un problema de validación o formato.

401

Falta autenticación o la clave API no es válida.

403

La identidad es válida, pero no tiene permisos suficientes para ese recurso.

404

El recurso no existe o no se encontró información para la consulta.

429

Se excedió el límite por minuto o la cuota del plan.

502 / 503

La fuente externa no está disponible o el servicio está temporalmente degradado.

Recomendaciones de manejo

• Trata 400 como error de entrada y corrige antes de reintentar
• Trata 401 como problema de credencial o encabezado
• Trata 429 con backoff y control de cuota
• Trata 502 y 503 como indisponibilidad temporal de fuente o servicio

Qué no conviene hacer

• no dependas de comparar textos exactos de detail
• no asumas que todos los endpoints se comportan igual frente a cache o trabajos asincrónicos
• no mezcles errores de validación con errores de disponibilidad externa

Precaución

No dependas de comparar textos exactos de detail. Para automatización, usa principalmente status y type.