Conceptos

Errores

Todos los errores tienen el mismo cuerpo: un objeto JSON con la llave error y una frase en inglés.

Forma de un error

{
  "error": "amount must be a positive integer in minor units"
}

El mensaje describe el problema con precisión y está pensado para tu log, no para mostrárselo al comprador. Cuando el error viene del procesador, la respuesta trae además un message con el detalle.

Códigos

Código	Significa	¿Reintentar?
`400`	El cuerpo no cumple el contrato: falta un campo, sobra otro o el tipo no corresponde.	No, hasta corregirlo
`401`	La llave falta, no existe o venció. Ver Llaves y entornos.	No
`404`	`{"error":"Route not found"}` — la ruta no existe. También cuando el recurso no es de tu organización.	No
`422`	El contrato está bien pero la operación es imposible: monto fuera del tope de un medio instantáneo, por ejemplo.	No
`500`	Algo se rompió de nuestro lado.	Sí, con espera creciente

Un recurso ajeno responde 404, no 403. Si pides un cobro que existe pero es de otra organización, la API contesta 404. Es a propósito: un 403 confirmaría que ese identificador existe.

Errores de validación más frecuentes

Mensaje	Qué corregir
`amount must be a positive integer in minor units`	Manda centavos, como entero. Ver Montos.
`instrument_id or provider_instrument_id is required`	Un cobro contra tarjeta guardada necesita saber qué tarjeta.
`cvv is required when initiator is customer (CIT)`	Si el cliente está presente, el CVV es obligatorio.
`cvv must not be sent when initiator is merchant (MIT)`	En un cobro automático no hay quien lo escriba: no lo mandes.
`parent_transaction_data is required for series MIT`	Un cobro recurrente tiene que apuntar al primero de la serie.
`installments.quantity must be an integer >= 2`	Para un pago sin cuotas, omite el objeto `installments`.
`success_url must be a valid URL`	Tiene que ser `http` o `https` absoluta.

Reintentos

La API no tiene claves de idempotencia. Un POST reintentado crea un cobro nuevo, no repite el anterior. Por eso solo conviene reintentar cuando la petición no llegó —un timeout de red o un 500— y aún así vale la pena guardar tu propio identificador en metadata para poder detectar el duplicado.

Tu identificador viaja en metadata

{
  "amount": 11900000,
  "metadata": { "order_id": "4821" }
}

Después puedes buscarlo: metadata vuelve en el objeto del cobro y en el evento del webhook, tal como lo mandaste.

Esta página en markdown: /docs/errores.md · Toda la documentación: /docs/llms-full.txt