Argentive Card sigue el contrato de errores HTTP estándar. Cuerpo siempre JSON con dos campos: error (string snake_case) y message (humano). Algunos errores incluyen campos extra como setupUrl o field.
Formato de respuesta
ejemplo 422
{
"error": "payment_method_required",
"message": "Cardholder ch_01HW... has no active payment method.",
"setupUrl": "https://checkout.mercadopago.com/...",
"cardholderId": "ch_01HW3FN4Y8K2RJTM9TWPXKP3VZ"
}
Códigos de error
400
Bad Request
Body inválido, campos faltantes o de tipo incorrecto.
El JSON de respuesta detalla qué campo falló.
401
Unauthorized
API key faltante, malformada o revocada.
Verificá el header Authorization y que la key no esté rotada.
402
Payment Required
El payment method del cardholder rechazó el hold.
Argentive detacha el payment method automáticamente. El cardholder debe re-onboardearlo vía /payment-method/setup.
403
Forbidden
Cuenta suspendida, en beta sin habilitación, o scope OAuth insuficiente.
Si pasó de un día para otro, escribinos.
404
Not Found
El recurso no existe O pertenece a otra organización.
Argentive nunca confirma existencia cross-tenant: cualquier ID ajeno al tuyo devuelve 404.
409
Conflict
Duplicado: el email del cardholder ya existe, o la idempotency key ya fue usada con otro body.
Para retries seguros, mantené la misma x-idempotency-key con el MISMO body.
422
Unprocessable Entity
El cardholder no tiene payment method activo.
La respuesta incluye un { setupUrl } para que el cardholder lo registre.
429
Too Many Requests
Pasaste el rate limit (1000 req/h por key).
Usá los headers X-RateLimit-Reset / Retry-After para backoff.
500
Internal Server Error
Algo nuestro falló. Reintentá con backoff exponencial.
Si persiste, hay incidente público en status.argentive.card.
502
Bad Gateway
Falló un provider downstream (card issuer o procesador de fondeo).
Generalmente transitorio. Reintentá con backoff.
Idempotency
Los endpoints POST /api/v1/cards y POST /api/v1/cardholders aceptan un header x-idempotency-key opcional. Si reintentás con la MISMA key dentro de 24h, Argentive devuelve la respuesta original sin volver a ejecutar el side effect.
Si reintentás con la misma x-idempotency-key pero un body distinto, Argentive devuelve 409 Conflict con el body original. Esto previene que un retry buggy emita dos cards distintas.
Estrategia recomendada de retries
Si recibís 429, 500 o 502, reintentá con backoff exponencial + jitter: