Formato de respuesta

Todas las respuestas de la API, exitosas o no, usan la misma envoltura JSON:

{
  "success": true,
  "message": "Consulta exitosa",
  "result": { }
}

Campo	Tipo	Descripción
success	boolean	true si la consulta devolvió datos.
message	string	Mensaje legible en español. Úsalo para registrar o mostrar el motivo de una falla.
result	object | array | null	Los datos de la consulta. null cuando no hay datos. En errores de validación puede traer errores.

Códigos HTTP

HTTP	success	Cuándo	¿Consume cuota?
200	true	Consulta exitosa.	Sí
200	false	La fuente oficial (SUNAT, RENIEC, SBS…) falló, está lenta o no tiene datos para lo que pediste.	No
400	false	Parámetros inválidos (DNI que no tiene 8 dígitos, RUC con dígito verificador incorrecto, fecha mal escrita…).	No
401	false	Sin token, token inválido, expirado o revocado.	No
403	false	Tu plan no incluye el módulo, no tienes plan activo, IP no permitida, cuenta suspendida o bloqueada.	No
404	false	El recurso no existe (por ejemplo, un archivo o un lote que no es tuyo).	No
429	false	Superaste el límite por minuto o la cuota mensual de tu plan o del módulo.	No
500	false	Error inesperado de ConsultaPe. Reintenta más tarde.	No

HTTP 200 con success: false

Que la fuente oficial falle no es un error de tu integración, por eso responde 200. Revisa siempre success además del código HTTP. Puedes reintentar más tarde: estas respuestas no consumen tu cuota.

Ejemplos

Falla de la fuente (HTTP 200):

{
  "success": false,
  "message": "No se encontraron datos para el DNI 12345678.",
  "result": null
}

Error de validación de un parámetro (HTTP 400):

{
  "success": false,
  "message": "El DNI debe tener 8 dígitos numéricos.",
  "result": null
}

Error de validación del cuerpo (HTTP 400). result.errores lista cada problema:

{
  "success": false,
  "message": "Datos inválidos",
  "result": {
    "errores": [
      "nombres should not be empty",
      "apellido_paterno must be shorter than or equal to 80 characters"
    ]
  }
}

Cuota agotada (HTTP 429):

{
  "success": false,
  "message": "Alcanzaste el límite mensual de 300 consultas de tu plan",
  "result": null
}

Convenciones de los datos

Dato	Formato
Fechas	YYYY-MM-DD (ej. 1980-10-25). Algunas fuentes (como SUNAT) publican fechas como texto dd/mm/yyyy; en ese caso se indica en la referencia.
Fecha y hora (*_at)	ISO 8601 en UTC (2026-10-04T15:20:11.000Z).
Textos	Nombres, razones sociales y direcciones en MAYÚSCULAS, tal como los publica la fuente.
fuente	Siempre consultape.pro (en tipo de cambio indica el tipo pedido: sunat o sbs).
desde_cache	true si la respuesta salió de datos guardados por ConsultaPe (más rápida).
ubigeo	Código INEI: ["15", "1501", "150122"] (departamento, provincia, distrito).
Identificadores	UUID (ej. 0192f6c4-9b1e-7c3a-8d2e-5f6a7b8c9d0e).

Listas paginadas

Los endpoints que devuelven listas aceptan pagina (desde 1) y por_pagina (máximo 100) y responden:

{
  "success": true,
  "message": "OK",
  "result": {
    "items": [],
    "total": 0,
    "pagina": 1,
    "por_pagina": 20
  }
}