Códigos de Error
Referencia completa de los errores que puede retornar la API y cómo manejarlos.
Formato de Respuesta de Error
Todos los errores siguen el mismo formato JSON:
{"detail": "Mensaje descriptivo en español","error_code": "categoria.error_especifico"}
El campo error_code usa el formato categoria.error para facilitar el manejo programático de errores.
Códigos HTTP
Bad Request
La petición tiene un formato inválido o faltan parámetros requeridos.
Posibles causas:
- •Formato de document_id incorrecto
- •JSON malformado en el body
- •Parámetros faltantes o inválidos
Unauthorized
No se proporcionó API Key o la key es inválida.
Posibles causas:
- •Header Authorization faltante
- •API Key expirada o revocada
- •Formato incorrecto del Bearer token
Forbidden
API Key válida pero sin permisos para el recurso.
Posibles causas:
- •API Key sin Clave SOL configurada (para Receptor)
- •Plan sin acceso a PDF
- •Cuota mensual agotada
- •Trial expirado
Not Found
El recurso solicitado no existe.
Posibles causas:
- •Comprobante no existe en SUNAT
- •Endpoint incorrecto
- •El documento aún no está disponible (esperar 24-72 horas)
Too Many Requests
Se ha excedido el límite de peticiones.
Posibles causas:
- •Demasiadas peticiones por minuto
- •Cuota mensual agotada
Internal Server Error
Error interno del servidor.
Posibles causas:
- •Error inesperado en el servidor
- •Problema temporal - reintentar
Bad Gateway
Error de comunicación con SUNAT.
Posibles causas:
- •Credenciales SUNAT incorrectas
- •SUNAT rechazó la autenticación
Service Unavailable
SUNAT no está disponible temporalmente. Incluye header Retry-After.
Posibles causas:
- •SUNAT no responde
- •Problema de red con SUNAT
- •Mantenimiento de SUNAT
Códigos de Error por Categoría
El campo error_code identifica el tipo específico de error:
auth.*Autenticación
Errores relacionados con la API Key y permisos
| Código | HTTP | Mensaje | Acción |
|---|---|---|---|
auth.invalid_api_key | 401 | API Key inválida o no proporcionada | Verificar API Key en el dashboard |
auth.api_key_required | 401 | Este endpoint requiere autenticación con API Key | Usar API Key (sk_live_xxx) en vez de session token |
auth.trial_expired | 403 | Tu período de prueba ha terminado | Suscribirse a un plan o comprar una bolsa |
auth.max_rucs_exceeded | 403 | Has alcanzado el límite de RUCs para tu plan | Actualizar a un plan superior |
auth.feature_not_allowed | 403 | Función no disponible en tu plan actual | Actualizar plan para acceder a esta función |
validation.*Validación
Errores en el formato de los datos enviados
| Código | HTTP | Mensaje | Acción |
|---|---|---|---|
validation.bad_request | 400 | Solicitud inválida | Revisar formato del request |
validation.invalid_ruc | 400 | RUC debe ser exactamente 11 dígitos numéricos | Validar RUC antes de enviar |
validation.invalid_document_id | 400 | Formato de documento inválido | Usar formato: {RUC}-{TipoDoc}-{Serie}-{Numero} |
sunat.*SUNAT
Errores relacionados con la comunicación con SUNAT
| Código | HTTP | Mensaje | Acción |
|---|---|---|---|
sunat.auth_failed | 502 | No se pudo validar las credenciales SUNAT | Verificar RUC/Usuario/Clave SOL en el dashboard |
sunat.request_failed | 503 | No se pudo obtener el documento de SUNAT | Reintentar usando el header Retry-After |
sunat.credentials_not_configured | 400 | API Key sin credenciales SUNAT configuradas | Configurar Clave SOL en la API Key (solo Receptor) |
rate_limit.*Rate Limiting
Límites de peticiones excedidos
| Código | HTTP | Mensaje | Acción |
|---|---|---|---|
rate_limit.exceeded | 429 | Límite de peticiones excedido | Esperar según header Retry-After |
server.*Servidor
Errores internos del servidor
| Código | HTTP | Mensaje | Acción |
|---|---|---|---|
server.service_unavailable | 503 | Servicio no disponible temporalmente | Reintentar usando el header Retry-After |
server.internal_error | 500 | Error interno del servidor | Contactar soporte si persiste |
Manejo de Errores Recomendado
async function downloadXML(documentId: string) {try {const response = await fetch(`https://api.integracpe.com/api/v1/sunat/receptor/xml/${documentId}`,{headers: {'Authorization': 'Bearer sk_live_tu_api_key'}});if (!response.ok) {const error = await response.json();const [category] = error.error_code.split('.');switch (category) {case 'auth':if (error.error_code === 'auth.trial_expired') {console.log('Trial expirado. Suscríbete a un plan.');// Redirigir a página de planes} else {console.log('Error de autenticación:', error.detail);}break;case 'sunat':if (error.error_code === 'sunat.request_failed') {const retryAfter = response.headers.get('Retry-After');console.log(`SUNAT no disponible. Reintentar en ${retryAfter}s`);// Implementar retry con backoff}break;case 'rate_limit':const retryAfter = response.headers.get('Retry-After');console.log(`Rate limit. Esperar ${retryAfter}s`);break;case 'validation':console.log('Error de validación:', error.detail);// Mostrar error al usuariobreak;default:console.log('Error:', error.detail);}throw new Error(error.detail);}return await response.json();} catch (error) {console.error('Error de conexión:', error);throw error;}}
Política de Reintentos
Reintentar
- ✓
429- Rate limit (usar Retry-After) - ✓
500- Error interno (esperar 5s) - ✓
502- Bad Gateway (esperar 30s) - ✓
503- SUNAT no disponible (usar Retry-After)
No Reintentar
- ✗
400- Request inválido - ✗
401- API Key inválida - ✗
403- Sin permisos / Trial expirado - ✗
404- No encontrado
Rate Limiting
La API incluye headers informativos sobre tu uso actual:
| Header | Descripción |
|---|---|
| X-RateLimit-Limit | Peticiones permitidas por minuto |
| X-RateLimit-Remaining | Peticiones restantes en el período actual |
| X-RateLimit-Limit-Type | Tipo de límite: per-minute o per-month |
| Retry-After | Segundos a esperar antes de reintentar (en 429 y 503) |
Logging
error_code completo en tus logs para facilitar el debugging. Es más útil que solo el código HTTP.Soporte
X-Request-ID).