Manejo de errores

Cada respuesta trae un code estable, un retryable y el código HTTP correcto, para que distingas sin ambigüedad “no existe” de “el servicio falló”.

El contrato

code es el contrato. Es un identificador estable pensado para tu lógica: enrutá por él, no por el texto.
message es la interfaz. Es texto legible que podemos reescribir o traducir; no lo uses para decidir.
retryable te dice si tiene sentido reintentar la misma consulta más tarde.
El HTTP acompaña al code, así la mayoría de clientes hace lo correcto sin leer el cuerpo.

Es aditivo: si hoy solo miras success, todo sigue funcionando igual.

Códigos

code	HTTP	retryable	Significado
found	200	No	Encontrado / operación exitosa.
invalid_input	400	No	Formato o parámetro inválido (DNI/RUC mal escrito, falta un campo, etc.).
invalid_sol_credentials	401	No	Las credenciales SOL (ruc/usuario/clave) enviadas no autenticaron en SUNAT.
document_not_found	404	No	La consulta funcionó y el documento no existe.
quota_exceeded	429	No	La consulta supera lo que resta de tu plan (endpoints por lote).
upstream_unavailable	503	Sí	El servicio no está disponible en este momento; reintenta más tarde.

Reintentos

Reintenta solo cuando retryable es true (código upstream_unavailable, HTTP 503): el servicio de origen no respondió y la consulta puede resolverse más tarde. Usa una espera creciente entre reintentos (por ejemplo 1s, 3s, 10s).

No reintentes un document_not_found (404), invalid_input (400) ni invalid_sol_credentials (401): el resultado no cambiará repitiendo la misma consulta.

Autenticación y cuota

Antes de procesar la consulta, la API valida tu acceso:

401 — token ausente o inválido, o correo sin verificar.
403 — tu plan no tiene acceso a este endpoint, o el origen (IP/dominio) no está autorizado.
429 — alcanzaste el límite de consultas de tu plan.
503 — no pudimos verificar tu plan en este momento; reintenta en unos segundos.

Ejemplos

200 Encontrado application/json

{
  "success": true,
  "code": "found",
  "retryable": false,
  "data": { "numero": "44556677", "nombre_completo": "..." }
}

404 No encontrado application/json

{
  "success": false,
  "code": "document_not_found",
  "retryable": false,
  "message": "El DNI no existe"
}

503 Servicio no disponible application/json

{
  "success": false,
  "code": "upstream_unavailable",
  "retryable": true,
  "message": "El servicio de consulta no está disponible en este momento. Intenta nuevamente en unos segundos."
}

400 Solicitud inválida application/json

{
  "success": false,
  "code": "invalid_input",
  "retryable": false,
  "message": "El DNI es incorrecto"
}