Errores y códigos HTTP
Qué significa cada código y qué hacer. No reintentes automáticamente errores de autenticación ni de validación; para el resto, guíate por retryable.
| HTTP | Causa | Acción sugerida |
|---|---|---|
| 401 | Token ausente o inválido/expirado. El cuerpo usa success: false y error.tipo/error.mensaje. | Verifica el encabezado Bearer y genera un token vigente. |
| 403 | Cuenta/suscripción no activa o IP de origen fuera de la allowlist. | Revisa el estado de la cuenta y la IP permitida configurada. |
| 409 | Se repitió una clave Idempotency-Key ya procesada. | No reenvíes la misma operación esperando una respuesta reproducida; la API responde conflicto sin volver a consultar SUNAT. |
| 422 | Algún campo no cumple el formato (por ejemplo, RUC sin 11 dígitos). | Corrige los campos indicados en el cuerpo JSON de respuesta. |
| 429 | Cuota del plan agotada o límite operativo por minuto excedido. Ambos rechazos usan success: false y error; el rechazo de cuota añade consumo/limite. | Para el límite por minuto, respeta Retry-After y sus encabezados de límite. Para cuota, revisa el saldo; no incluye Retry-After, aunque sí puede incluir X-RateLimit-Limit/X-RateLimit-Remaining. |
| 503 | El contador temporal de solicitudes no está disponible. La API responde success: false y error.tipo: rate_limit_unavailable. | Espera al menos el segundo indicado por Retry-After y reintenta. La respuesta actual incluye Retry-After: 1, X-RateLimit-Limit y X-RateLimit-Remaining: 0; si persiste, contacta al administrador del servicio. |
| 404 / 500 | RUC/DNI devuelven 404 si el documento no existe o SUNAT no respondió (distínguelos con retryable). CPE, validación múltiple y buzón devuelven 500 si su salida no es exitosa. | Revisa code, retryable y message cuando existan. Una consulta válida enviada a SUNAT consume cuota incluso ante estos errores. Si reenvías la operación con una clave de idempotencia nueva, se procesa y consume otra vez. |
Ejemplos de cuerpos de error
401 · Falta el token
{
"success": false,
"error": {
"tipo": "no_autenticado",
"mensaje": "Token requerido"
}
}
422 · RUC con caracteres no numéricos
{
"success": false,
"code": "invalid_ruc",
"retryable": false,
"message": "El RUC debe tener 11 dígitos",
"time": 0
}
El primero se recibe cuando falta Authorization: Bearer. El segundo corresponde a un RUC de 11 caracteres no numéricos; no se envía a SUNAT y no consume cuota.