Errores

Formato de error

Todos los errores de Pay-In responden success: false y un message legible.

Error de validación (422): la petición tiene campos no válidos. No se creó, cotizó ni cobró nada.

{
  "success": false,
  "status": false,
  "message": "The selected country is invalid.",
  "errors": {
    "country": ["The selected country is invalid."]
  }
}

• errors asocia cada campo no válido con sus mensajes.
• status: false es un alias obsoleto de success: false. Lee success.
• Algunas cuentas reciben además field_errors[]: una entrada por campo con field, code y expected_format (nunca el valor que enviaste).

Error de dominio (cualquier estado): la petición se entendió pero no se puede hacer.

{
  "success": false,
  "message": "A deposit already exists for this external_identifier or idempotency key with a different payload.",
  "code": "PARTNER_PAYIN_IDEMPOTENCY_CONFLICT"
}

• code es una clave de error estable. Es opcional: léela cuando venga, pero no dependas de ella. Un 422 de validación nunca la lleva.
• En PARTNER_PAYIN_PROVIDER_REJECTED, un provider_reason opcional (code: "INVALID_FIELD", field, message) indica el campo del pagador que hay que corregir.

Estados HTTP

HTTP	Significado	Qué hacer
200	Éxito.	—
401	Unauthorized.: credenciales ausentes o no válidas, credenciales del otro entorno, o una clave deshabilitada, revocada o vencida.	Revisa la clave y su estado en el Portal de Desarrolladores. Ver Autenticación.
403	No permitido: IP fuera de la lista blanca de la clave (IP address is not allowed.), endpoint no permitido para la clave (Insufficient permissions.), o el método de pago no está habilitado para tu cuenta.	Corrige la lista blanca de IPs o contacta con Cashela.
404	El recurso no existe o no es tuyo, o no hay catálogo para tus filtros.	Revisa la referencia, el país o el método.
409	Conflicto con el estado actual: identificador repetido con otro cuerpo, depósito aún no final, ya revertido…	Mira el código. No reintentes a ciegas.
422	Campos no válidos, o una regla de negocio rechazó la petición. No se creó ni se cobró nada.	Corrige y vuelve a enviar (con un external_identifier nuevo si el depósito fue rechazado).
429	Demasiadas peticiones.	Espera los segundos de Retry-After y reintenta con espera progresiva.
500	Error inesperado.	Reintenta más tarde. Si persiste, contacta con soporte con tu X-Trace-Id.
502	Falló la red de pago al crear el depósito.	Consulta el depósito antes de enviar una petición nueva.
503	Una dependencia (tasa de cambio, catálogo) no está disponible temporalmente.	Reintenta más tarde.

Códigos de error

Código	HTTP	Endpoint	Qué hacer
(validación, errors.<campo>[])	422	Todos	Corrige el campo. No se creó nada. Ver Datos del pagador y documentos.
PARTNER_PAYIN_CATALOG_EMPTY	404	Países	Ningún país coincide con tus filtros para tu cuenta.
PARTNER_PAYIN_COUNTRY_NOT_FOUND	404	Métodos de pago, depósito	País desconocido.
PARTNER_PAYIN_PAYMENT_METHOD_NOT_FOUND	404	Tasas de cambio, depósito	El método no está disponible para ese país, cuenta o entorno. Vuelve a consultar los métodos.
PARTNER_PAYIN_TRANSACTION_NOT_FOUND	404	Consultar un depósito	Referencia desconocida, o un depósito de otra cuenta.
PARTNER_PAYIN_RAIL_NOT_ENABLED_FOR_TENANT	403	Depósito	Este método de pago no está habilitado para tu cuenta. Contacta con Cashela.
PARTNER_PAYIN_IDEMPOTENCY_CONFLICT	409	Depósito	Mismo Idempotency-Key / external_identifier con otro cuerpo. Usa un identificador nuevo para un depósito nuevo. Ver Idempotencia.
PARTNER_PAYIN_EXTERNAL_IDENTIFIER_CONFLICT	409	Depósito	Ya existe un depósito con ese external_identifier.
PARTNER_PAYIN_AMOUNT_BELOW_MINIMUM	422	Depósito	El importe está por debajo del mínimo del método. El mensaje indica el límite.
PARTNER_PAYIN_AMOUNT_ABOVE_MAXIMUM	422	Depósito	El importe supera el máximo del método.
PARTNER_PAYIN_LIMIT_EXCEEDED	422	Depósito	El depósito supera un límite de procesamiento de tu llave (por depósito, por día o por hora). No se creó ni cobró nada. Ver Límites de procesamiento.
PARTNER_PAYIN_ROUTE_UNAVAILABLE	422	Depósito	El método no está disponible temporalmente (availability.executable: false). Ofrece otro método o reintenta más tarde.
PARTNER_PAYIN_PROVIDER_REJECTED	422	Depósito	La red de pago rechazó el depósito, normalmente por los datos del pagador. Revisa provider_reason, corrige los datos y crea un depósito nuevo. No reenvíes los mismos datos.
PARTNER_PAYIN_COMPLIANCE_BLOCKED	422	Métodos de pago, depósito	Rechazado por motivos de cumplimiento. No reintentes; contacta con Cashela si lo necesitas.
PARTNER_PAYIN_PROVIDER_ERROR	502	Depósito	Fallo técnico de la red de pago. Consulta el depósito antes de volver a intentarlo.
PARTNER_PAYIN_FX_UNAVAILABLE	503	Cotizaciones, depósito	Tasa de cambio no disponible temporalmente. Reintenta más tarde.
PARTNER_PAYIN_CALLBACK_NOT_FINAL	409	Reenviar notificación	El depósito todavía no es final.
PARTNER_PAYIN_SIMULATION_ALREADY_FINAL	409	Simulate de sandbox	El depósito ya es final.
PARTNER_PAYIN_REFUNDS_DISABLED	403	Anulación, reembolso	Las anulaciones y reembolsos con tarjeta no están disponibles temporalmente. Reintenta más tarde.
PARTNER_PAYIN_REVERSAL_NOT_SUPPORTED	422	Anulación, reembolso	Solo se pueden anular o reembolsar depósitos con tarjeta.
PARTNER_PAYIN_DEPOSIT_ALREADY_REVERSED	409	Anulación	Ya revertido por completo. No se movió nada.
PARTNER_PAYIN_PARTIAL_REFUND_DECLINED	409	Reembolso	Un reembolso parcial necesita un cobro liquidado.
PARTNER_PAYIN_REFUND_IN_PROGRESS	409	Reembolso	Hay otro reembolso en curso. Reintenta en unos momentos.
PARTNER_PAYIN_DEPOSIT_CHARGED_BACK	409	Reembolso	Tuvo contracargo; no se puede reembolsar.
PARTNER_PAYIN_REFUND_EXCEEDS_ORIGINAL	422	Reembolso	Más de lo que queda por reembolsar, o ya revertido por completo.
PARTNER_PAYIN_REFUND_PARTIALLY_REFUNDED	422	Reembolso	Reembolso total después de uno parcial: envía el amount restante.
PARTNER_PAYIN_INVALID_REVERSAL_AMOUNT	422	Reembolso	El amount debe ser positivo.
PARTNER_PAYIN_PARTIAL_REFUND_UNSUPPORTED	422	Reembolso	Este depósito no admite reembolso parcial.

Límites de procesamiento

Cada llave de API puede tener límites sobre lo que procesa: lo máximo que puede pedir un depósito, lo máximo por día (UTC) y la cantidad máxima de depósitos por hora. Cashela los fija contigo; pídele a Cashela que los suba o los baje.

Un depósito que supera uno se rechaza antes de crear o cobrar nada, con 422 y el código PARTNER_PAYIN_LIMIT_EXCEEDED. limits[] trae una entrada por cada límite superado:

{
  "success": false,
  "message": "The deposit exceeds the limits of this credential.",
  "code": "PARTNER_PAYIN_LIMIT_EXCEEDED",
  "limits": [
    {
      "field": "amount",
      "code": "DAILY_LIMIT",
      "message": "The daily limit is 1,000.00 USD and 250.00 USD is left today (UTC); it resets at 00:00 UTC."
    }
  ]
}

limits[].code	Límite superado	Qué hacer
PER_DEPOSIT_LIMIT	El importe supera lo máximo que puede pedir un depósito.	Envía un importe menor.
DAILY_LIMIT	Los depósitos creados hoy (UTC) más este superan el límite diario. El mensaje dice cuánto queda.	Envía un importe menor, o espera a las 00:00 UTC.
HOURLY_LIMIT	Se crearon demasiados depósitos en la última hora.	Reintenta más tarde.

Los depósitos rechazados, fallidos, declinados, cancelados o vencidos no cuentan para el día ni para la hora. Repetir una petición que ya creó un depósito (mismo external_identifier / Idempotency-Key y cuerpo) devuelve ese depósito; no se vuelve a comprobar contra los límites.

Cuándo reintentar

Situación	¿Reintentar?
Timeout, error de conexión, 500, 503 en Crear un depósito	Sí, con el mismo external_identifier / Idempotency-Key y el mismo cuerpo. Recibes el depósito original si se llegó a crear.
502 PARTNER_PAYIN_PROVIDER_ERROR	Primero consulta el depósito.
422 de validación	No. Corrige la petición.
422 PARTNER_PAYIN_LIMIT_EXCEEDED	HOURLY_LIMIT: sí, más tarde. DAILY_LIMIT: a partir de las 00:00 UTC, o con un importe menor. PER_DEPOSIT_LIMIT: no con el mismo importe.
422 PARTNER_PAYIN_PROVIDER_REJECTED	No con los mismos datos. Corrígelos y usa un external_identifier nuevo.
409	No. Lee el código y el depósito.
429	Sí, después de Retry-After.
401 / 403	No. Corrige las credenciales, la lista blanca de IPs o la configuración de la cuenta.

Envía siempre un X-Trace-Id y regístralo con la respuesta, para que soporte pueda encontrar tu petición.