Códigos de error

Todas las fallas usan la envoltura estándar { "success": false, "message": "...", "result": ... }. Usa el código HTTP para decidir qué hacer y el message para registrar el detalle.

Resumen

HTTP	Significado	¿Reintentar?
200 + success:false	La fuente oficial falló o no tiene datos.	Sí, más tarde (no consume cuota). Si el mensaje dice que no hay datos, no tiene sentido reintentar enseguida.
400	Parámetros inválidos.	No. Corrige la petición.
401	No autenticado o token inválido.	No. Revisa el token.
403	Sin permiso: plan, IP, cuenta suspendida o bloqueada.	No. Revisa tu plan o la configuración del token.
404	Recurso no encontrado.	No.
409	Conflicto (ya existe un registro con esos datos).	No.
413	El archivo enviado es demasiado grande.	No. Envía un archivo más pequeño.
429	Límite por minuto o cuota mensual.	Sí, tras esperar (por minuto) o al ampliar el plan (mensual).
500	Error inesperado de ConsultaPe.	Sí, con espera. Si persiste, avísanos.
502 / 504	La API no respondió a tiempo (por ejemplo, durante un despliegue).	Sí, con espera.

Mensajes frecuentes

400 — validación

Mensaje	Causa
El DNI debe tener 8 dígitos numéricos.	DNI con letras o con otra longitud.
El número de RUC no es válido.	RUC que no tiene 11 dígitos, prefijo distinto de 10/15/16/17/20 o dígito verificador incorrecto.
La fecha 'desde' debe tener el formato AAAA-MM-DD.	Fecha mal escrita en tipo de cambio.
El rango máximo es de 366 días.	Rango de tipo de cambio demasiado largo.
El mes solicitado aún no tiene tipo de cambio.	Mes futuro.
El archivo debe ser .xlsx, .xls o .txt.	Formato no admitido en validez masiva.
El XML no es un comprobante UBL válido (Invoice, CreditNote o DebitNote).	Archivo inválido en PDF desde XML.
Datos inválidos	El cuerpo JSON no cumple el formato. El detalle está en result.errores.

401 — autenticación

Mensaje	Causa
No autenticado	Falta la cabecera Authorization o x-api-key.
Token de API inválido o revocado	Token mal copiado, expirado o revocado.
Esta ruta no acepta token de API	Llamaste con un token cp_ a una ruta que solo usa la web (por ejemplo /app/...).

403 — permisos

Mensaje	Causa
No tienes un plan activo. Contacta con soporte para activarlo.	Tu cuenta no tiene suscripción vigente.
Tu plan no incluye esta consulta	El módulo del endpoint no está en tu plan.
IP no autorizada para este token (x.x.x.x)	El token tiene lista de IPs y la tuya no está.
Tu cuenta está suspendida	Cuenta suspendida.
Acceso bloqueado	IP o cuenta bloqueada.

429 — límites

Mensaje	Causa
Superaste el límite de N consultas por minuto de tu plan	Demasiadas llamadas en el mismo minuto.
Alcanzaste el límite mensual de N consultas de tu plan	Cuota mensual del plan agotada.
Alcanzaste el límite mensual de N consultas de este módulo	Cuota mensual del módulo agotada.

200 con success: false — fuente oficial

Ejemplos:

• No se encontraron datos para el DNI 12345678.
• No se encontraron coincidencias.

Recomendación de manejo

async function consultar(url) {
  const r = await fetch(url, { headers: { Authorization: `Bearer ${process.env.CONSULTAPE_TOKEN}` } });
  const cuerpo = await r.json();

  if (r.ok && cuerpo.success) return cuerpo.result;           // éxito
  if (r.ok) throw new Error(`Fuente no disponible: ${cuerpo.message}`); // 200 + success:false → reintentar luego
  if (r.status === 429) throw new Error(`Límite alcanzado: ${cuerpo.message}`);
  throw new Error(`Error ${r.status}: ${cuerpo.message}`);
}