Ir al contenido

Beta privada · apertura 23 de diciembre

Errores

Todos los errores tienen la misma forma. El codigo no cambia entre versiones: programa contra él, no contra el mensaje.

{
"error": {
"codigo": "saldo_insuficiente",
"mensaje": "No te alcanza el saldo para esta operación.",
"detalle": { "disponible": "12.40", "requerido": "15.00" },
"request_id": "req_8f2c1a7d",
"docs": "https://docs.opennexum.com/errores#saldo_insuficiente",
"recarga_url": "https://app.opennexum.com/recargar"
}
}
  • mensaje explica en español qué pasó y cómo se arregla.
  • detalle trae los datos para corregirlo (por ejemplo, cada campo con su problema).
  • request_id también viaja en la cabecera X-Request-Id; menciónalo si escribes a soporte.
  • docs apunta a la sección de esta página; recarga_url aparece solo en errores de saldo.
Código HTTP
validacion 400
clave_invalida 401
saldo_insuficiente 402
tope_alcanzado 402
permiso_faltante 403
emisor_obligado_ose 403
no_encontrado 404
idempotencia_en_conflicto 409
solicitud_en_curso 409
ya_registrado 409
ventana_cerrada 409
boveda_inactiva 409
estado_no_permite 409
plazo_vencido 409
sunat_rechazo 422
credenciales_sunat 422
limite_uso 429
error_interno 500
servicio_externo_no_disponible 502
no_disponible 503
operacion_no_disponible 501

HTTP 400 · Solicitud incorrecta

Algún dato no cumple el formato. En detalle va cada campo con su problema.

HTTP 401 · No autorizado

Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como Authorization: Bearer onx_live_….

HTTP 402 · Pago requerido

No te alcanza el saldo para esta operación. Pásale recarga_url a una persona de tu cuenta para que recargue.

La respuesta trae recarga_url y, en detalle, el saldo disponible y lo requerido. Un agente no recarga: le pasa el enlace a una persona y espera. Más en Saldo y error 402.

HTTP 402 · Pago requerido

La clave llegó a su tope de gasto del periodo. Una persona de tu cuenta puede subirlo desde el panel.

También responde 402 con recarga_url; en el panel una persona sube el tope de la clave. Más en Saldo y error 402.

HTTP 403 · Prohibido

La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.

HTTP 403 · Prohibido

Ese RUC figura en el padrón de obligados a emitir mediante un OSE; por ahora no podemos emitir por él.

HTTP 404 · No encontrado

No existe o no pertenece a tu cuenta.

HTTP 409 · Conflicto

Usaste la misma Idempotency-Key con otro cuerpo. Genera una clave nueva para cada operación distinta.

Más en Idempotencia.

HTTP 409 · Conflicto

Ya estamos procesando una petición con esa Idempotency-Key. Espera unos segundos y vuelve a consultar.

Más en Idempotencia.

HTTP 409 · Conflicto

Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.

HTTP 409 · Conflicto

La conversación está fuera de la ventana de atención: solo puedes escribir con una plantilla aprobada. detalle.plantillas_sugeridas trae opciones.

HTTP 409 · Conflicto

La bóveda de credenciales todavía no está activa. Envía credenciales en cada llamada.

HTTP 409 · Conflicto

El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.

HTTP 409 · Conflicto

Pasó el plazo que da SUNAT para esta operación. Para anular una factura fuera de plazo, emite una nota de crédito.

HTTP 422 · No procesable

SUNAT rechazó el comprobante. En detalle van el código y la descripción que dio SUNAT.

HTTP 422 · No procesable

SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.

HTTP 429 · Demasiadas peticiones

Hiciste demasiadas peticiones seguidas. Espera los segundos que indica Retry-After y vuelve a intentar.

La respuesta trae la cabecera Retry-After con los segundos de espera. Más en Límites y error 429.

HTTP 500 · Error interno

Algo falló de nuestro lado. Repite la petición con la misma Idempotency-Key: no se duplica nada.

Menciona el request_id si escribes a soporte.

HTTP 502 · Mala puerta de enlace

SUNAT, el BCRP o el proveedor de mensajería no respondió. Revisa el estado antes de reenviar.

HTTP 503 · Servicio no disponible

El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica Retry-After.

La respuesta trae la cabecera Retry-After con los segundos de espera.

HTTP 501 ·

Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.