Errores

La forma de los errores del API, los códigos HTTP y qué hacer con cada código.

Decide con el código HTTP y error.code, que es estable.
En un 400 invalid_request, lee details.field y details.code.
Reintenta solo lo que se puede reintentar, respetando Retry-After.

Un llamado sin llave secreta

curl -s https://api-epay.dev.n1co.dev/v1/payment_intents/pi_UGF5bWVudEludGVudEV4YW1w

401 Unauthorized

{
  "error": {
    "code": "invalid_api_key",
    "message": "a valid secret key is required: Authorization: Bearer sk_..."
  }
}

El sobre de error#

Campo	Descripción
`error.code`	Código estable en inglés. Úsalo en tu código.
`error.message`	Texto en inglés para tus logs. Puede cambiar; no lo muestres.
`error.details`	Datos adicionales en algunos códigos, como `field` y `code`.

Los mensajes nunca repiten lo que enviaste. La validación informa solo el primer campo que falla.

Códigos HTTP#

HTTP	Significado	¿Reintentar?
`400`	La solicitud no es válida.	No. Corrige la solicitud.
`401`	Falta la llave o no es válida.	No. Revisa tu llave.
`404`	El objeto no existe en tu tienda.	No.
`409`	Conflicto con el estado actual.	Según el código.
`413`	El cuerpo pasa de 16 KiB.	No.
`415`	`Content-Type` no es `application/json`.	No.
`422`	n1co no aceptó la solicitud.	Según el código.
`429`	Demasiadas solicitudes.	Sí, después de `Retry-After`.
`500`	Error interno.	Sí, con espera creciente.
`503`	n1co no está disponible por ahora.	Sí, después de `Retry-After` cuando viene.

Códigos generales#

`error.code`	HTTP	Qué hacer
`invalid_request`	400	Lee `details.field` y `details.code` y corrige.
`invalid_api_key`	401	Revisa `Authorization: Bearer sk_…`.
`request_too_large`	413	Reduce el cuerpo a 16 KiB o menos.
`unsupported_media_type`	415	Envía `Content-Type: application/json`.
`rate_limited`	429	Espera los segundos de `Retry-After`.
`internal_error`	500	Reintenta más tarde. Si persiste, contacta a n1co.
`n1co_api_unavailable`	503	Reintenta después de `Retry-After`.
`platform_access_pending`	503	El acceso de ePay a tu tienda no está listo. Reintenta después de `Retry-After`.

Un details.code unknown_field significa una clave no documentada; details.field la nombra, como customer.<clave> dentro del cliente. Los nombres distinguen mayúsculas y minúsculas.

Configuración#

Códigos de POST /v1/setup. Ninguno guarda nada: puedes repetir la configuración.

`error.code`	HTTP	Qué hacer
`invalid_request`	400	El cuerpo o la `webhook_url` no es válido; el mensaje nombra el campo.
`invalid_credentials`	401	n1co rechazó el client id o el client secret.
`store_already_enabled`	409	No había nada que cambiar. `details` trae `store_id` y `publishable_key`.
`client_id_in_use`	409	Esa aplicación ya está vinculada a otra tienda.
`setup_conflict`	409	Otra configuración de la tienda corría al mismo tiempo. Reintenta.
`missing_roles`	422	`details.missing_roles` lista los roles que faltan.
`client_app_not_found`	422	n1co no conoce la aplicación. Revisa el client id.
`rate_limited`	429	5 por minuto por `client_id`, 60 por minuto en total. Espera `Retry-After`.
`n1co_api_unavailable`	503	Repite después de `Retry-After` (30 s).
`platform_access_pending`	503	El acceso a tu aplicación aún no está listo. Repite después de `Retry-After`.
`platform_certificate_mismatch`	503	Un problema de configuración del lado de n1co. Contacta a n1co.

Sesiones de tarjeta y tarjetas#

`error.code`	HTTP	Qué hacer
`card_session_not_found`	404	La sesión no existe en tu tienda.
`card_not_found`	404	`payment_method` no es una tarjeta del cliente con ese `customer.id`.
`card_unavailable`	409	La tarjeta ya no se puede usar. El comprador escribe otra vez su tarjeta.

`details.code`	Significado
`missing_customer`, `invalid_customer`	Falta `customer` o no es un objeto.
`missing_id`, `invalid_id`, `missing_name`, `invalid_name`, `missing_email`, `invalid_email`, `missing_phone`, `invalid_phone`	Un campo del cliente; `details.field` es `customer.<campo>`.
`unknown_field`	Una clave no documentada; dentro del cliente, `details.field` es `customer.<clave>`.
`invalid_page_origins`	`page_origins` no es válido.

Pagos#

`error.code`	HTTP	Qué hacer
`payment_intent_not_found`	404	El intent no existe en tu tienda.
`payment_intent_not_cancelable`	409	Solo se cancela en `requires_payment_method` o `requires_action`; ver `details.status`.

Al crear un payment intent, details.code puede ser:

`details.code`	Significado
`missing_amount`, `invalid_amount`	Falta `amount` o no es un entero de 1 a 1000000000.
`missing_currency`, `invalid_currency`	Falta `currency` o no es un código ISO 4217.
`currency_not_supported`	La moneda no tiene dos decimales.
`currency_mismatch`	Tu tienda cobra en otra moneda.
`missing_customer`, `invalid_customer`, códigos de campo del cliente	Como en las sesiones de tarjeta.
`invalid_description`, `invalid_reference`, `invalid_metadata`	El campo no cumple sus reglas.
`invalid_billing`, `missing_country`, `invalid_country`, `invalid_state`, `invalid_postal_code`	La facturación no es válida.
`invalid_page_origins`	`page_origins` no es válido.
`invalid_payment_method`	`payment_method` no es un `id` de tarjeta.

Fallos de un pago#

Un intento fallido no es un error HTTP: llega en last_error del intent, con code, decline_code y message. n1co.js traduce message para el comprador.

`last_error.code`	Qué pasó	Qué hacer
`card_declined`	El banco rechazó el cargo; `decline_code` trae su código.	Otra tarjeta, o que el comprador llame a su banco.
`card_rejected`	n1co no aceptó la tarjeta nueva.	Pide otra tarjeta.
`card_unavailable`	La tarjeta guardada dejó de servir.	Cobra con el card element.
`billing_required`	La tarjeta necesita dirección de facturación.	Confirma otra vez con `billing`.
`invalid_request`	n1co rechazó la solicitud.	Pide otra tarjeta.
`authentication_failed`	3D Secure no se completó.	Deja reintentar.
`authentication_expired`	3D Secure venció sin respuesta (10 minutos).	Deja reintentar.
`provider_error`	n1co respondió algo que no se pudo usar.	Reintenta en unos minutos.
`outcome_unknown`	No se sabe si hubo cargo; el intent sigue en `processing`.	No cobres otra vez. Espera el webhook.
`currency_mismatch`, `amount_mismatch`	n1co cobró otra moneda u otro monto; se anuló y se canceló.	Crea otro intent.

Reembolsos#

`error.code`	HTTP	Qué hacer
`payment_intent_not_found`	404	El intent no existe en tu tienda.
`refund_not_found`	404	El reembolso no existe en tu tienda.
`payment_intent_not_refundable`	409	`details.reason` dice por qué (tabla siguiente).
`refund_exists`	409	Ya tiene un reembolso que no se reenvía ahora; `details.refund` es su `id`.
`refund_in_progress`	409	Se está enviando; espera `Retry-After`.
`n1co_api_unavailable`, `platform_access_pending`	503	No se envió nada. El siguiente `POST` lo envía.

`details.reason`	Qué pasó
`not_succeeded`	El intent no está `succeeded`.
`order_unknown`	El pago no tiene número de orden de n1co. Contacta a n1co.
`attempts_exhausted`	El reembolso ya se envió 3 veces.

`details.code`	Significado
`unknown_field`	Una clave no documentada, incluido `amount`.
`missing_payment_intent`, `invalid_payment_intent`	Falta `payment_intent` o no es válido.
`invalid_reason`	`reason` no tiene de 1 a 150 caracteres o tiene caracteres de control.
`invalid_metadata`	`metadata` no es válido.

Un rechazo de n1co llega en last_error del reembolso:

`last_error.code`	`status`	Qué hacer
`refund_rejected`	`failed`	Lee `message`, el texto de n1co. Reenvía o contacta a n1co.
`provider_error`	`failed`	Reenvía más tarde o contacta a n1co.
`order_not_found`	`failed`	n1co no conoce la orden. Contacta a n1co.
`outcome_unknown`	`pending`	Espera el webhook; reenvía pasados 3 minutos.

Eventos#

`error.code`	HTTP	Qué hacer
`event_not_found`	404	El evento no existe en tu tienda.

`details.code`	Significado
`invalid_limit`	`limit` no es un entero de 1 a 100.
`invalid_type`	`type` no es un tipo de evento.
`unknown_parameter`, `duplicate_parameter`, `invalid_query`	Un parámetro no documentado, repetido o ilegible.

Errores en el navegador#

Los errores de capture() y confirmPayment() son de n1co.js, no del API. Están en la referencia de n1co.js.

Cuándo reintentar#

Situación	Reintento
`429` y `503` con `Retry-After`	Espera esos segundos y repite.
`500`, o un error de red sin respuesta	Repite con espera creciente.
`409 setup_conflict`	Repite enseguida.
`400`, `401`, `404`, `413`, `415`	No repitas sin corregir.