Idempotencia, errores y límites

Si una solicitud agota el tiempo de espera, no sabes si tuvo éxito. Reintenta la misma operación con la misma Idempotency-Key para evitar crear un segundo pago.

Una clave por acción

1. Genera una clave única antes de la primera solicitud y guárdala con tu pedido.
2. Envíala en Idempotency-Key al crear o cambiar un recurso de negocio.
3. Tras un tiempo de espera agotado, reintenta el mismo método, ruta y cuerpo con esa clave.
4. Para una acción nueva, crea una clave nueva.

La clave debe ser no vacía y de como máximo 128 bytes. Repetir una acción completada devuelve su respuesta guardada. Cambiar el cuerpo con la misma clave devuelve 409 idempotency_conflict.

Esto se aplica a mutaciones de negocio como facturas, tiendas, claves y webhooks. Las llamadas GET de solo lectura y los retos de inicio de sesión no usan este mecanismo. Sigue los requisitos de cada endpoint.

external_id ayuda a asociar un pago con tu pedido; no es una clave de idempotencia.

Consulta errores por código

Ejemplo:

{"error":{"code":"idempotency_conflict","message":"idempotency_conflict"}}

Usa error.code en tu programa. No infieras el éxito a partir del cuerpo de la respuesta sin comprobar antes el estado HTTP.

Código	Próxima acción
unauthorized	Comprueba la credencial, los permisos y cualquier restricción de IP. Inicia sesión de nuevo si la sesión caducó.
mfa_required	Completa el segundo factor de la cuenta usando su sesión.
onboarding_required	Completa /onboarding antes de las operaciones de tienda.
idempotency_key_required	Proporciona una clave guardada no vacía, de como máximo 128 bytes.
idempotency_conflict	Localiza la solicitud original. No crees un nuevo pago en silencio.
json_content_type_required / invalid_json	Envía Content-Type: application/json y solo campos documentados.
unsupported_network / unsupported_asset	Elige una red y un token compatibles.
network_not_ready / asset_not_ready	Espera a que esté disponible o elige otra ruta lista.
amount_below_minimum / fee_exceeds_amount	Comprueba el importe, los decimales y las condiciones de la tienda.
shop_archived / shop_not_found	Comprueba la tienda y el acceso.
invalid_expires_in	Envía 1d, 7d, 30d, 180d o 365d, y solo al crear una factura. Los depósitos no caducan.
invalid_assets / issuance_in_group	Envía pares {chain_id, token} distintos sin chain_id ni token; cancela o pausa un grupo mediante su propio id. Consulta varios tokens o redes.
solana_setup_required / tron_setup_required	Configura antes el destinatario de Solana o Tron de la tienda.
invoice_amount_limit / sandbox_amount_limit	Reduce el importe hasta el límite.
active_invoice_limit_reached / deposit_address_limit_reached	Cancela facturas o deshabilita depósitos que ya no necesites, o pídele a Invoise que aumente el límite.
api_key_limit_reached / too_many_allowed_ips / webhook_limit_reached	Revoca claves sin usar, acorta la lista de IP o reutiliza un endpoint existente.
team_limit_reached	Elimina a un miembro o revoca una invitación pendiente, o pídele a Invoise que aumente el límite.
account_disabled	El personal de Invoise bloqueó la cuenta; el motivo está en error.details. Consulta cuentas bloqueadas.
rate_limited	Espera el número de segundos indicado en Retry-After antes de reintentar.

Límites

Cuando una solicitud superaría un límite, Invoise la rechaza con el cuerpo de error habitual y el código de abajo.

Límite	Valor	Error
Importe de una factura	1,000,000 tokens	400 invoice_amount_limit
Importe de una factura sandbox o transferencia simulada	10,000 tokens	400 sandbox_amount_limit
Facturas activas por comercio	2,000	400 active_invoice_limit_reached
Direcciones de depósito activas por comercio, por familia de red	EVM 10,000, Tron 10,000, Solana 10	400 deposit_address_limit_reached
Claves de API por tienda no revocadas	10	400 api_key_limit_reached
Direcciones IP o rangos CIDR permitidos por clave	10	400 too_many_allowed_ips
Endpoints de webhook por tienda	10	400 webhook_limit_reached
Miembros del equipo e invitaciones pendientes por comercio	10	400 team_limit_reached
Solicitudes por minuto	1,200, de las cuales como máximo 120 no son GET	429 rate_limited

Los límites de importe están en tokens enteros, no en unidades base. Todos los tokens compatibles son stablecoins de dólar, así que 1,000,000 tokens equivale aproximadamente a $1,000,000.

Una factura está activa hasta que se paga, se cancela o caduca. Una factura ofrecida en varias redes cuenta una sola vez. Una dirección de depósito está activa hasta que se deshabilita; cada opción de red de un depósito es una dirección independiente. Sandbox y producción se cuentan por separado para ambos límites. El personal de Invoise puede cambiar los límites de facturas, direcciones de depósito y equipo de un comercio.

El límite de equipo se aplica tanto al invitar como al aceptar una invitación. La URL de un endpoint de webhook se puede cambiar, así que puedes reutilizar un endpoint en lugar de añadir uno nuevo.

Las solicitudes se cuentan por clave de API, por sesión del panel, o por IP del cliente cuando no está autenticado. Una respuesta 429 incluye Retry-After: 60.

Reintenta sin duplicados

Reintenta los tiempos de espera agotados y los errores temporales del servidor con la misma clave, usando retrasos crecientes. Ante un 429, espera los segundos indicados en Retry-After; no envíes más solicitudes de inmediato. Corrige los errores de entrada inválida y de acceso antes de reintentar.

Para los webhooks, Invoise reintenta la entrega. Acepta el evento de forma duradera, devuelve 2xx y luego procésalo. Evita duplicados usando Invoise-Event-ID.

Las rutas antiguas /projects son alias de /shops, incluido su alcance de idempotencia. Usa /shops para las integraciones nuevas. Los nombres de error heredados pueden usar project_*.