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" }}mensajeexplica en español qué pasó y cómo se arregla.detalletrae los datos para corregirlo (por ejemplo, cada campo con su problema).request_idtambién viaja en la cabeceraX-Request-Id; menciónalo si escribes a soporte.docsapunta a la sección de esta página;recarga_urlaparece 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 |
validacion
Sección titulada «validacion»HTTP 400 · Solicitud incorrecta
Algún dato no cumple el formato. En detalle va cada campo con su problema.
clave_invalida
Sección titulada «clave_invalida»HTTP 401 · No autorizado
Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como Authorization: Bearer onx_live_….
saldo_insuficiente
Sección titulada «saldo_insuficiente»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.
tope_alcanzado
Sección titulada «tope_alcanzado»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.
permiso_faltante
Sección titulada «permiso_faltante»HTTP 403 · Prohibido
La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.
emisor_obligado_ose
Sección titulada «emisor_obligado_ose»HTTP 403 · Prohibido
Ese RUC figura en el padrón de obligados a emitir mediante un OSE; por ahora no podemos emitir por él.
no_encontrado
Sección titulada «no_encontrado»HTTP 404 · No encontrado
No existe o no pertenece a tu cuenta.
idempotencia_en_conflicto
Sección titulada «idempotencia_en_conflicto»HTTP 409 · Conflicto
Usaste la misma Idempotency-Key con otro cuerpo. Genera una clave nueva para cada operación distinta.
Más en Idempotencia.
solicitud_en_curso
Sección titulada «solicitud_en_curso»HTTP 409 · Conflicto
Ya estamos procesando una petición con esa Idempotency-Key. Espera unos segundos y vuelve a consultar.
Más en Idempotencia.
ya_registrado
Sección titulada «ya_registrado»HTTP 409 · Conflicto
Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.
ventana_cerrada
Sección titulada «ventana_cerrada»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.
boveda_inactiva
Sección titulada «boveda_inactiva»HTTP 409 · Conflicto
La bóveda de credenciales todavía no está activa. Envía credenciales en cada llamada.
estado_no_permite
Sección titulada «estado_no_permite»HTTP 409 · Conflicto
El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.
plazo_vencido
Sección titulada «plazo_vencido»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.
sunat_rechazo
Sección titulada «sunat_rechazo»HTTP 422 · No procesable
SUNAT rechazó el comprobante. En detalle van el código y la descripción que dio SUNAT.
credenciales_sunat
Sección titulada «credenciales_sunat»HTTP 422 · No procesable
SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.
limite_uso
Sección titulada «limite_uso»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.
error_interno
Sección titulada «error_interno»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.
servicio_externo_no_disponible
Sección titulada «servicio_externo_no_disponible»HTTP 502 · Mala puerta de enlace
SUNAT, el BCRP o el proveedor de mensajería no respondió. Revisa el estado antes de reenviar.
no_disponible
Sección titulada «no_disponible»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.
operacion_no_disponible
Sección titulada «operacion_no_disponible»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.