Errores · Documentación de la API

Códigos HTTP y códigos de error de la API, qué significa cada uno, cuáles descuentan créditos y cómo manejarlos desde tu sistema.

Usa el código HTTP para decidir qué hacer y el campo error para distinguir el caso. message es un texto en español pensado para mostrarse a una persona; error no cambia entre versiones y es el que debes comparar en tu código.

Tabla de códigos

HTTP	`error`	Significado	Créditos
200	—	Consulta con resultado.	1
401	`token_invalido`	Falta la API key o no es válida.	0
402	`sin_creditos`	No queda saldo en ninguna de tus bolsas.	0
403	`token_inactivo`	La API key está desactivada o revocada.	0
403	`cuenta_suspendida`	La cuenta está suspendida.	0
404	`no_encontrado`	El dato no existe en la fuente: RUC no inscrito, DNI sin registro, búsqueda sin coincidencias, tipo de cambio sin ningún valor disponible.	0
422	`validacion`	El dato enviado no tiene el formato esperado. `detalles` indica el campo y el motivo.	0
501	`no_disponible`	La fuente de esa API aún no está conectada (hoy, carnet de extranjería).	0
502	`error_fuente`	La fuente no respondió o respondió mal. Puedes reintentar.	0

Las respuestas que pasan la autenticación (200, 402, 404, 422, 501 y 502) quedan en tu Historial del panel, con el dato consultado enmascarado.

Ejemplos

Formato inválido (422):

respuesta.json

{  "success": false,  "message": "Revisa los datos enviados.",  "error": "validacion",  "data": null,  "detalles": {    "ruc": "RUC inválido: deben ser 11 dígitos con dígito verificador correcto."  },  "meta": {    "consultado_en": "2026-10-12T08:41:49Z"  }}

Sin créditos (402):

respuesta.json

{  "success": false,  "message": "No tienes créditos disponibles. Compra un paquete o mejora tu plan.",  "error": "sin_creditos",  "data": null,  "meta": {    "consultado_en": "2026-10-12T08:41:49Z"  }}

Mensajes de validación por API

API	Campo en `detalles`	Mensaje
RUC, anexos, representantes, trabajadores	`ruc`	RUC inválido: deben ser 11 dígitos con dígito verificador correcto.
DNI	`dni`	DNI inválido: deben ser 8 dígitos.
Ubigeo por código	`ubigeo`	Ubigeo inválido: deben ser 6 dígitos.
Ubigeo por nombres	`departamento`	Indica el departamento para buscar la provincia.
Ubigeo por nombres	`provincia`	Indica departamento y provincia para buscar el distrito.
Razón social	`q`	Escribe entre 3 y 80 caracteres.
Carnet de extranjería	`numero`	Carnet de extranjería inválido: 9 a 12 caracteres alfanuméricos.

Cómo manejarlos

404 no es un fallo: es la respuesta normal cuando el dato no existe. Trátalo como "sin resultado" y no lo reintentes: la fuente no va a cambiar en los próximos segundos. No descuenta créditos.
Otros 4xx: corrige la petición (formato, token o saldo). Reintentar sin cambiar nada devuelve lo mismo.
502 y otros 5xx: reintenta con una espera creciente (por ejemplo 1, 2 y 4 segundos) y un máximo de intentos. No descuentan créditos.
Tiempo de espera: pon un timeout en tu cliente HTTP y trátalo como un 5xx.
Valida antes de enviar: el formato del RUC (11 dígitos y dígito verificador) y del DNI (8 dígitos) se puede comprobar en tu sistema; te ahorras llamadas que terminarían en 422.

Guía completa: Manejo de errores y reintentos al consumir APIs.