Errors

Error envelope

Every Pay-In error answers success: false and a human-readable message.

Validation error (422): the request has invalid fields. Nothing was created, quoted or charged.

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

• errors maps each invalid field to its messages.
• status: false is a deprecated alias of success: false. Read success.
• Some accounts also receive field_errors[]: one entry per field with field, code and expected_format (never the value you sent).

Domain error (any status): the request was understood but cannot be done.

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

• code is a stable error key. It is optional: read it when present, never require it. A validation 422 never carries it.
• On PARTNER_PAYIN_PROVIDER_REJECTED, an optional provider_reason (code: "INVALID_FIELD", field, message) names the payer field to correct.

HTTP statuses

HTTP	Meaning	What to do
200	Success.	—
401	Unauthorized.: missing or invalid credentials, credentials of the other environment, or a disabled, revoked or expired key.	Check the key and its status in the Developer Portal. See Authentication.
403	Not allowed: IP not in the key’s whitelist (IP address is not allowed.), endpoint not allowed for the key (Insufficient permissions.), or the payment method is not enabled for your account.	Fix the IP whitelist or contact Cashela.
404	The resource does not exist or does not belong to you, or there is no catalog for your filters.	Check the reference, country or method.
409	Conflict with the current state: repeated identifier with a different body, deposit not final yet, already reversed…	See the code. Do not retry blindly.
422	Invalid fields, or a business rule refused the request. Nothing was created or charged.	Fix and send again (with a new external_identifier if the deposit was refused).
429	Too many requests.	Wait Retry-After seconds, then retry with backoff.
500	Unexpected error.	Retry later. If it persists, contact support with your X-Trace-Id.
502	The payment network failed while creating the deposit.	Read the deposit before sending a new request.
503	A dependency (exchange rate, catalog) is temporarily unavailable.	Retry later.

Error codes

Code	HTTP	Endpoint	What to do
(validation, errors.<field>[])	422	All	Correct the field. Nothing was created. See Payer data & documents.
PARTNER_PAYIN_CATALOG_EMPTY	404	Countries	No country matches your filters for your account.
PARTNER_PAYIN_COUNTRY_NOT_FOUND	404	Payment methods, deposit	Unknown country.
PARTNER_PAYIN_PAYMENT_METHOD_NOT_FOUND	404	Exchange rates, deposit	The method is not available for that country, account or environment. List the methods again.
PARTNER_PAYIN_TRANSACTION_NOT_FOUND	404	Get a deposit	Unknown reference, or a deposit of another account.
PARTNER_PAYIN_RAIL_NOT_ENABLED_FOR_TENANT	403	Deposit	This payment method is not enabled for your account. Contact Cashela.
PARTNER_PAYIN_IDEMPOTENCY_CONFLICT	409	Deposit	Same Idempotency-Key / external_identifier with a different body. Use a new identifier for a new deposit. See Idempotency.
PARTNER_PAYIN_EXTERNAL_IDENTIFIER_CONFLICT	409	Deposit	A deposit with this external_identifier already exists.
PARTNER_PAYIN_AMOUNT_BELOW_MINIMUM	422	Deposit	The amount is below the method’s minimum. The message gives the limit.
PARTNER_PAYIN_AMOUNT_ABOVE_MAXIMUM	422	Deposit	The amount is above the method’s maximum.
PARTNER_PAYIN_LIMIT_EXCEEDED	422	Deposit	The deposit crosses a processing limit of your key (per deposit, per day or per hour). Nothing was created or charged. See Processing limits.
PARTNER_PAYIN_ROUTE_UNAVAILABLE	422	Deposit	The method is temporarily unavailable (availability.executable: false). Offer another method or retry later.
PARTNER_PAYIN_PROVIDER_REJECTED	422	Deposit	The payment network refused the deposit, usually because of the payer’s data. Check provider_reason, correct the data and create a new deposit. Do not resend the same data.
PARTNER_PAYIN_COMPLIANCE_BLOCKED	422	Payment methods, deposit	Refused for compliance reasons. Do not retry; contact Cashela if needed.
PARTNER_PAYIN_PROVIDER_ERROR	502	Deposit	Technical failure of the payment network. Read the deposit before trying again.
PARTNER_PAYIN_FX_UNAVAILABLE	503	Quotes, deposit	Exchange rate temporarily unavailable. Retry later.
PARTNER_PAYIN_CALLBACK_NOT_FINAL	409	Re-send notification	The deposit is not final yet.
PARTNER_PAYIN_SIMULATION_ALREADY_FINAL	409	Sandbox simulate	The deposit is already final.
PARTNER_PAYIN_REFUNDS_DISABLED	403	Void, refund	Card voids and refunds are temporarily not available. Retry later.
PARTNER_PAYIN_REVERSAL_NOT_SUPPORTED	422	Void, refund	Only card deposits can be voided or refunded.
PARTNER_PAYIN_DEPOSIT_ALREADY_REVERSED	409	Void	Already fully reversed. Nothing moved.
PARTNER_PAYIN_PARTIAL_REFUND_DECLINED	409	Refund	A partial refund needs a settled charge.
PARTNER_PAYIN_REFUND_IN_PROGRESS	409	Refund	Another refund is in progress. Retry shortly.
PARTNER_PAYIN_DEPOSIT_CHARGED_BACK	409	Refund	Charged back; cannot be refunded.
PARTNER_PAYIN_REFUND_EXCEEDS_ORIGINAL	422	Refund	More than what is left refundable, or already fully reversed.
PARTNER_PAYIN_REFUND_PARTIALLY_REFUNDED	422	Refund	Full refund after a partial one: send the remaining amount.
PARTNER_PAYIN_INVALID_REVERSAL_AMOUNT	422	Refund	The amount must be positive.
PARTNER_PAYIN_PARTIAL_REFUND_UNSUPPORTED	422	Refund	Partial refund not supported for this deposit.

Processing limits

Each API key can have limits on what it processes: the most one deposit may ask for, the most per day (UTC) and the most deposits per hour. Cashela sets them with you; ask Cashela to raise or lower them.

A deposit that crosses one is refused before anything is created or charged, with 422 and the code PARTNER_PAYIN_LIMIT_EXCEEDED. limits[] has one entry per limit crossed:

{
  "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	Limit crossed	What to do
PER_DEPOSIT_LIMIT	The amount is above the most one deposit may ask for.	Send a smaller amount.
DAILY_LIMIT	The deposits created today (UTC) plus this one are above the daily limit. The message says what is left.	Send a smaller amount, or wait for 00:00 UTC.
HOURLY_LIMIT	Too many deposits were created in the last hour.	Retry later.

Deposits that were refused, failed, declined, cancelled or expired do not count towards the day or the hour. Repeating a request that already created a deposit (same external_identifier / Idempotency-Key and body) returns that deposit; it is not checked against the limits again.

Retry guidance

Situation	Retry?
Timeout, connection error, 500, 503 on Create a deposit	Yes, with the same external_identifier / Idempotency-Key and the same body. You get the original deposit if it was created.
502 PARTNER_PAYIN_PROVIDER_ERROR	Read the deposit first.
422 validation	No. Fix the request.
422 PARTNER_PAYIN_LIMIT_EXCEEDED	HOURLY_LIMIT: yes, later. DAILY_LIMIT: after 00:00 UTC, or with a smaller amount. PER_DEPOSIT_LIMIT: not with the same amount.
422 PARTNER_PAYIN_PROVIDER_REJECTED	Not with the same data. Correct the data and use a new external_identifier.
409	No. Read the code and the deposit.
429	Yes, after Retry-After.
401 / 403	No. Fix credentials, IP whitelist or account settings.

Always send an X-Trace-Id and log it with the response, so support can find your request.