Documentación / Referencia
Códigos de error
El cuerpo de un error siempre tiene la misma forma. Básese en code, no en el texto: el texto está pensado para personas y puede cambiar.
JSON
{ "error": { "code": "duplicate_order", "message": "Ya existe una factura para este order_id" } }Cuándo es seguro reintentarAnte
429, 500, 503, idempotency_in_progress y errores de red, con el mismo Idempotency-Key: no se crearán duplicados.Solicitud y acceso
| HTTP | code | Causa y qué hacer |
|---|---|---|
| 400 | bad_json, bad_body | El cuerpo no es JSON, tiene campos de más o un importe numérico en lugar de una cadena: corrija la solicitud |
| 400 | bad_idempotency_key | Falta la clave o su formato no es válido: 8–128 caracteres ASCII imprimibles, sin empezar por d: |
| 400 | bad_query | Parámetros de listado no válidos |
| 401 | unauthorized | Firma, hora, nonce o clave: consulte CP-HMAC |
| 403 | merchant_suspended | El comercio está suspendido: contacte con el soporte |
| 403 | merchant_not_approved | La configuración no ha terminado o la solicitud está en revisión: complete el asistente en el panel |
| 403 | billing_suspended | Hay una factura de comisión impagada: páguela en el panel, en «Facturación»; la suspensión se levantará de inmediato |
| 404 | not_found | La factura no existe o pertenece a otro comercio |
| 413 | body_too_large | El cuerpo supera el límite: reduzca metadata |
| 429 | rate_limited | Demasiadas solicitudes: reintente con espera exponencial |
| 500 | internal | Error interno: reintente con el mismo Idempotency-Key |
Facturas e idempotencia
| HTTP | code | Causa y qué hacer |
|---|---|---|
| 409 | duplicate_order | El order_id ya se ha usado: use uno nuevo, por ejemplo ORDER-1001-2 |
| 409 | idempotency_conflict | La misma clave con otro cuerpo |
| 409 | idempotency_in_progress | La primera solicitud aún se está procesando: reintente en 1–2 s |
| 409 | invoice_not_payable | La factura ha vencido o está cerrada: cree una nueva |
| 422 | invalid_order_id, invalid_price_amount, invalid_price_currency, invalid_return_url, invalid_expires_in_seconds, invalid_metadata | Un campo no ha superado la validación: el texto indica la regla |
| 422 | invalid_allowed_assets | Ninguno de los activos de la lista está disponible: el texto da el motivo de cada uno |
| 422 | no_assets | No hay ningún activo disponible: revise las billeteras y los activos en el panel |
| 422 | amount_too_small | El importe es inferior al mínimo de todos los activos disponibles |
Elección de moneda en la página de pago
Estos errores los gestiona la página de pago; su servidor solo los verá si llama a select directamente.
| HTTP | code | Causa |
|---|---|---|
| 409 | asset_locked | Cambio de moneda después de un pago |
| 409 | wallet_not_configured | No hay una billetera de cobro activa para esa red |
| 409 | wallet_changed, address_conflict | Repita la elección |
| 422 | asset_not_allowed | El activo no está en la factura o ya no está permitido |
| 503 | rate_unavailable | No hay un tipo de cambio confirmado: ofrezca una stablecoin |
| 503 | network_unavailable | Los cobros en esa red no están disponibles temporalmente: elija otra |
Reembolsos
| HTTP | code | Causa |
|---|---|---|
| 403 | merchant_inactive | La tienda está suspendida o la clave se ha revocado |
| 409 | invoice_not_paid | La factura no tiene un activo elegido: no hay nada que reembolsar |
| 409 | nothing_to_refund | Todo ya se ha reembolsado o solicitado |
| 409 | too_many_refunds | Hay 20 solicitudes abiertas para la factura |
| 409 | refund_executor | El reembolso lo ejecuta la plataforma, no usted |
| 409 | invoice_status_changed | El estado de la factura cambió tras la solicitud: reintente con "ack_status_change": true |
| 422 | amount_exceeds_refundable | El importe supera el disponible: redúzcalo o use "full" |
| 422 | invalid_amount, invalid_address, invalid_tx_hash | Un campo no ha superado la validación |