Saltar al contenido principal
Docs Sitio Planes

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.

HTTPCausaAcción sugerida
401Token ausente o inválido/expirado. El cuerpo usa success: false y error.tipo/error.mensaje.Verifica el encabezado Bearer y genera un token vigente.
403Cuenta/suscripción no activa o IP de origen fuera de la allowlist.Revisa el estado de la cuenta y la IP permitida configurada.
409Se 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.
422Algún campo no cumple el formato (por ejemplo, RUC sin 11 dígitos).Corrige los campos indicados en el cuerpo JSON de respuesta.
429Cuota 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.
503El 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 / 500RUC/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.