Formato de respuesta

Todas las respuestas de /v1 usan el mismo envoltorio JSON (success, message, data y meta) y las mismas cabeceras de créditos.

Toda respuesta de /v1, con éxito o con error, es un objeto JSON con la misma forma. Tu código solo necesita mirar success y, según el caso, data o error.

Respuesta con éxito

HTTP 200:

respuesta.json

{  "success": true,  "message": "Consulta exitosa",  "data": {    "fecha": "2026-10-12",    "moneda": "USD",    "compra": 3.45,    "venta": 3.457,    "fuente": "SUNAT"  },  "meta": {    "fuente": "SUNAT",    "consultado_en": "2026-10-12T07:40:12Z",    "creditos_cobrados": 1,    "creditos_disponibles": 14621  }}

Campo	Tipo	Contenido
`success`	boolean	`true`.
`message`	string	`"Consulta exitosa"`.
`data`	object	El resultado. Sus campos dependen de cada API y están descritos en la referencia.
`meta`	object	Información sobre la consulta (abajo).

El objeto `meta`

Campo	Contenido
`fuente`	Entidad de la que proviene el dato: `SUNAT`, `RENIEC`, `INEI`.
`consultado_en`	Fecha y hora de la consulta en UTC, formato ISO 8601 (`2026-10-12T07:40:12Z`).
`creditos_cobrados`	Créditos descontados por esta respuesta: `1` cuando hubo resultado.
`creditos_disponibles`	Créditos que te quedan sumando todas tus bolsas, después de esta consulta.

En las respuestas con error meta solo trae consultado_en.

Respuesta con error

HTTP 4xx o 5xx. success es false, data es null y aparece error, un código estable pensado para tu programa; message es un texto en español que puedes mostrar tal cual.

respuesta.json

{  "success": false,  "message": "No se encontró información para la consulta.",  "error": "no_encontrado",  "data": null,  "meta": {    "consultado_en": "2026-10-12T08:41:49Z"  }}

En los errores de validación (422) se agrega detalles, un objeto con el campo y el motivo. La lista completa de códigos está en Errores.

Cabeceras

Cabecera	Contenido
`Content-Type`	`application/json`
`X-Credits-Charged`	Lo mismo que `meta.creditos_cobrados`.
`X-Credits-Remaining`	Lo mismo que `meta.creditos_disponibles`.

Las cabeceras X-Credits-* vienen en todas las respuestas que pasaron la autenticación, también en los errores 402, 404, 422, 501 y 502 (con X-Credits-Charged: 0). En los errores 401 y 403 no, porque la petición no llegó a asociarse a una cuenta.

Convenciones de `data`

Codificación UTF-8: los textos conservan tildes y la letra eñe.
Los textos de SUNAT, RENIEC e INEI llegan en mayúsculas, tal como los publica la fuente ("ACTIVO", "HABIDO", "LIMA").
Las fechas tienen formato AAAA-MM-DD; los periodos mensuales, AAAA-MM.
null significa que la fuente no tiene ese dato. No es lo mismo que false ni que una cadena vacía.
Los números de documento y los códigos (ruc, dni, ubigeo) son cadenas, para conservar los ceros a la izquierda.
Las cantidades y los tipos de cambio son números (12577, 3.446).

Leer la respuesta en tu código

consulta.js

const res = await fetch('https://api.endpoint.pe/v1/ruc/20131312955', {  headers: { Authorization: 'Bearer TU_TOKEN' },});const body = await res.json();if (body.success) {  console.log(body.data.razon_social, body.data.estado);} else {  console.log(res.status, body.error, body.message);}

consulta.py

import requestsres = requests.get(    'https://api.endpoint.pe/v1/ruc/20131312955',    headers={'Authorization': 'Bearer TU_TOKEN'},)body = res.json()if body['success']:    print(body['data']['razon_social'], body['data']['estado'])else:    print(res.status_code, body['error'], body['message'])