API Error Handling

When you integrate with Cashfree Payouts APIs, handle errors in a predictable way so your application can recover without creating duplicate or misleading outcomes. Every API response should be treated as a contract: inspect the top-level status, then use the returned sub-code and message to decide whether to retry, correct the request, or surface a merchant-friendly error.

Error response structure

Cashfree APIs typically return a response with a top-level status field and an error payload when the request can’t be completed successfully. A typical error response looks like this:

Use the sub-code as the main decision point in your integration. Error messages can change over time, but the sub-code is the stable signal for handling logic.

How to handle errors

Follow these steps for every API call:

Check the top-level status field first.
If the response is ERROR, inspect the subCode and map it to an action.
For client-side issues such as validation failures, update the request data and resubmit only after correcting the input.
For temporary service issues such as rate limits or server errors, retry with backoff and jitter.
If the operation is asynchronous or the transfer moves into a pending state, use the status APIs or webhooks to track the final outcome.

Example

The following example shows a simple pattern for handling a failed response:

const response = await payouts.createTransfer(payload);

if (response.status === "ERROR") {
  if (["429", "500", "503", "520"].includes(response.subCode)) {
    await retryWithBackoff(payload);
  } else {
    throw new Error(response.message);
  }
}

Common error categories

The exact sub-code can vary by endpoint, but the following categories are the most common in Payouts integrations.

Category	Typical sub-code	Description	Recommended action
Bad request	`400` or `422`	The request body or parameters are invalid.	Fix the request data and retry after correcting the input.
Authentication failure	`401` or `403`	The API credentials are missing, invalid, or not authorised.	Verify your credentials and account permissions.
Resource not found	`404`	The beneficiary, transfer, or referenced resource doesn’t exist.	Confirm the identifier and create or fetch the correct resource first.
Conflict or precondition failed	`409` or `412`	The request conflicts with the current state or account conditions.	Check the resource state, balance, or account restrictions before retrying.
Rate limit	`429`	Too many requests were sent in a short period.	Slow down the request rate and retry after a short delay.
Temporary server issue	`500`, `502`,`503`, or `520`	Cashfree or an upstream service is temporarily unavailable.	Retry with exponential backoff and don’t treat the request as permanently failed.

Retry and recovery guidance

Retrying isn’t always safe. Retry only when the failure is temporary and the operation can be repeated without creating duplicate outcomes. Treat errors as part of the integration design rather than as an afterthought.

Classify each failure as user-correctable, retryable, or terminal.
Don’t retry validation errors, authentication failures, or permanent bank declines until the underlying issue is fixed.
For 429 and 5XX errors, retry with exponential backoff and brief jitter.
Preserve the same request reference across retries when possible to avoid duplicate payouts.
For asynchronous payout flows, don’t assume a request is final until the status API or webhook confirms the terminal state.

When not to retry

Don’t retry automatically when the error is caused by:

Invalid beneficiary or transfer details
Missing or invalid credentials
Insufficient balance or account restrictions
A manual approval step that must be completed first
A permanent downstream decline or bank rejection

Recommended approach

Build your integration around three outcomes:

Success: Continue the workflow and update the merchant view.
Retryable failure: Retry the request after a short delay.
Permanent failure: Stop, surface the issue clearly, check the input accuracy or contact support if needed.

If you are using Cashfree SDKs, catch the raised exception and map it to the same decision logic described above.

Payouts

One Escrow

Cashgram

Payout Protect

Change Log

Error Handling

Error response structure

How to handle errors

Example

Common error categories

Retry and recovery guidance

When not to retry

Recommended approach

​Error response structure

​How to handle errors

​Example

​Common error categories

​Retry and recovery guidance

​When not to retry

​Recommended approach

Error response structure

How to handle errors

Example

Common error categories

Retry and recovery guidance

When not to retry

Recommended approach