# Errores

Toda respuesta de error lleva `error.codigo`, estable, y `error.documentacion` con el enlace aquí.

| Estado | Código | Qué hacer |
|---|---|---|
| 401 | `token_invalido` | Revisa la cabecera `Authorization: Bearer`. El token pudo expirar o ser revocado. |
| 401 | `ip_no_permitida` | El token tiene allowlist de IPs y la petición no sale de ninguna. Se cambia desde el panel. |
| 403 | `scope_insuficiente` | El scope efectivo es la intersección del token con el plan: mira `scopes_efectivos` en `/me` para saber cuál de los dos falta. |
| 403 | `finalidad_no_declarada` | Faltan finalidad, base legal o el anexo de tratamiento firmado. Es requisito para servir identidad y se resuelve con nosotros, no en el código. |
| 403 | `tenant_suspendido` | La cuenta está suspendida. Contacta con soporte. |
| 403 | `sin_plan_vigente` | La cuenta no tiene suscripción vigente. Sin plan no hay scopes, así que esto no se arregla esperando. |
| 422 | `documento_invalido` | El RUC o el DNI no pasan la validación de formato o de dígito verificador. Valídalo en tu lado y ahorras la llamada. |
| 429 | `rate_limit_excedido` | Vas demasiado rápido. Reintenta pasado lo que diga `Retry-After`. |
| 429 | `presupuesto_agotado` | El presupuesto mensual de consultas a fuentes externas se agotó. El documento podría existir; no es un 404. |
| 429 | `cuota_agotada` | La cuota del periodo se acabó y el plan no permite excedente. Se arregla subiendo de plan. |
| 429 | `tope_excedente_alcanzado` | El plan sí permite excedente, pero se alcanzó el tope de gasto configurado para tu cuenta. Se arregla subiendo el tope, no el plan. |
| 429 | `tope_de_pruebas_alcanzado` | Un token de prueba admite un número de consultas al día, y ya se usaron. Se reinicia a medianoche (hora de Lima); para más, usa un token live, que gasta tu cuota. |
| 403 | `no_disponible_en_sandbox` | Un token de prueba responde con el sandbox, un conjunto fijo y sintético, y esta operación solo tiene sentido con datos reales. Usa un token live. |
| 422 | `tope_watch_alcanzado` | El plan no admite más listas de vigilancia o más RUC vigilados. No es un problema del documento: se arregla subiendo de plan, o dejando de vigilar lo que ya no interesa. |
| 429 | `intentos_agotados` | Ya se verificó ese documento las veces que se permiten en la ventana. Es una protección: probar nombres contra un documento sería la forma de averiguarlo. Vuelve pasado lo que diga `Retry-After`, con el nombre que te dio el titular. |
| 503 | `servicio_no_disponible` | Una pieza del servicio que esta operación necesita no responde, y por seguridad no se responde sin ella. Es nuestro, no de tu petición: reintenta en unos segundos. |
| 422 | `credencial_sol_no_configurada` | Para validar comprobantes hacen falta tus credenciales de la API de la SUNAT (client_id y client_secret, que generas en SOL). Se cargan con nosotros: nunca se usan las de otro. |
| 422 | `credencial_sol_rechazada` | La SUNAT no acepta tus credenciales de SOL. Genera unas nuevas en SUNAT Operaciones en Línea y cárgalas otra vez: esperar no lo arregla. |
| 503 | `fuente_no_disponible` | La fuente oficial no respondió a tiempo. No es tu petición ni se cobra: reintenta en unos segundos. |