Errores y reintentos

Rutas /v1

Todo error tiene la misma forma. Decida por code y retryable, no por el texto, que puede cambiar:

{"error": {"code": "MTC_UNAVAILABLE", "message": "El MTC no respondió: ...", "retryable": true}}

code	HTTP	Cuándo	¿Reintentar?	Qué hacer
`INVALID_REQUEST`	422 / 405	La petición no es válida: un dato con formato incorrecto (una placa que no tiene 6 letras o números, un lote vacío o demasiado grande) o un método que la ruta no admite. Dentro del estado de un comprobante: SUNAT no aceptó los datos de ese comprobante.	No	Corregir la petición; repetirla igual dará el mismo error.
`UNAUTHORIZED`	401	Falta la API key, no existe o su cliente está desactivado.	No	Revisar la cabecera X-API-Key o pedir una clave a Pytronia.
`NOT_FOUND`	404	La ruta no existe.	No	Revisar la dirección contra la referencia.
`RATE_LIMITED`	429	Se superó el límite de peticiones por minuto de la API key, el tope de consultas por hora al MTC o el de consultas por minuto a SUNAT.	Sí	Esperar los segundos de la cabecera Retry-After y reintentar.
`SERVICE_DISABLED`	503	El servicio pedido está desactivado en este servidor.	No	Consultar con Pytronia; reintentar no sirve.
`MTC_UNAVAILABLE`	503	El MTC no responde, está atendiendo otra consulta o está en pausa tras un fallo.	Sí	Esperar los segundos de la cabecera Retry-After y reintentar; antes, dará el mismo error.
`MTC_FORMAT_CHANGED`	502	La consulta del MTC cambió o pidió verificación humana; queda suspendida y Pytronia recibe el aviso.	No	No reintentar; consultar con Pytronia.
`SUNAT_UNAVAILABLE`	503	SUNAT no respondió o falló. En un lote, sale en cada comprobante afectado; el lote entero falla así solo si no se pudo consultar ninguno.	Sí	Reintentar pasado un minuto, o lo que diga la cabecera Retry-After.
`SUNAT_CREDENTIALS_REJECTED`	403	SUNAT rechazó las credenciales de la aplicación: no existen, se revocaron o la aplicación no está registrada para el servicio pedido.	No	Revisar las credenciales de la aplicación en SOL; repetir la petición dará el mismo error.
`SUNAT_FORMAT_CHANGED`	502	SUNAT respondió algo que el servicio no sabe leer; Pytronia recibe el aviso. En un lote, sale en cada comprobante afectado; el lote entero falla así solo si no se pudo leer ninguno.	No	No reintentar; consultar con Pytronia.
`INTERNAL_ERROR`	500	Fallo inesperado del propio servicio.	Sí	Reintentar más tarde; si se repite, escribir a Pytronia con el X-Request-Id de la respuesta.

Rutas de comprobantes

Responden {"detail": ...}: un texto, salvo en el 422. Si el texto empieza por SUNAT error:, el fallo es de SUNAT y no del servicio.

HTTP	Cuándo	¿Reintentar?
401	Falta la API key, o SUNAT no aceptó el acceso: usuario o clave SOL, permiso del usuario o credenciales de la aplicación. El motivo va en `detail`	No: corregir lo que dice `detail`
403	`API key no autorizada`: la clave no existe o está desactivada	No
404	El comprobante no está en SUNAT o no tiene ese archivo	No
422	Falta algún campo del cuerpo o no tiene el formato esperado. Aquí `detail` es una lista: un elemento por campo que falla, con `loc` (el campo), `msg`, `type` e `input`	No: corregir el cuerpo
429	Se superó el límite por minuto de la API key	Sí, en un minuto
500, 502, 503, 504 con `SUNAT error:`	Fallo de SUNAT. Su consulta falla al azar con frecuencia	Sí

El 422 repite lo que usted envió

Cada elemento de detail lleva en input lo que llegó, credenciales incluidas. No lo guarde en logs ni lo reenvíe: para pedir ayuda basta el X-Request-Id.

Cómo reintentar

Reintente solo lo que las tablas dicen: repetir un error de la petición (4xx) dará siempre lo mismo.
Si la respuesta trae la cabecera Retry-After, espere exactamente esos segundos. La traen los 429, los MTC_UNAVAILABLE y los SUNAT_UNAVAILABLE.
En el estado de comprobantes, un error con un comprobante va dentro de la respuesta 200, en su campo error, con el mismo code y retryable que en esta tabla.
Tras un fallo del MTC, el servicio no vuelve a consultarlo durante 60 segundos: reintentar antes solo devuelve el mismo 503.
Con los 429 de las rutas de comprobantes, espere un minuto.
Con los fallos de SUNAT (SUNAT error:), hasta 3 intentos con espera creciente, por ejemplo 2, 4 y 8 segundos: su consulta falla al azar y al reintentar suele salir.
Si un error se repite, guarde el X-Request-Id de la respuesta y vea Soporte.