Error handling and retry strategy

View as Markdown

• View as Markdown

  Open this page as Markdown
• Copy for LLM

  Copy page as Markdown for LLMs
• Open in Claude

  Get insights from Claude
• Open in ChatGPT

  Get insights from ChatGPT

Payments Direct 2.0 returns a standardized error response for every failed API request. Building a reliable integration means classifying errors correctly, retrying safely, and escalating promptly when retrying won't help.

This topic covers:

• How to classify errors using the code and type fields
• Which errors are safe to retry, and how to retry them
• Recommended exponential backoff parameters
• Handling authentication errors
• Handling payment failures (FAILED, DECLINED, RETURNED states)
• What to log and monitor

Classify before you act

Every error response includes a code field (for example, USR_067) and a type field (for example, USER_ERROR). Always use the code field as your primary signal, not the HTTP status code alone. Two errors can share an HTTP status but require completely different handling.

Error type reference

Transient vs. permanent errors

Before retrying, confirm that the error is transient (a condition that may resolve itself) rather than permanent.

Retry strategy

Exponential backoff with jitter

When a request fails with a retryable error (SYSTEM_ERROR / 500, or AUTH_ERROR / 401 after a token refresh), use exponential backoff with jitter rather than retrying immediately or at a fixed interval. Immediate or synchronized retries amplify load on an already stressed system and can trigger rate limiting.

Recommended approach:

1. On the first failure, wait a short base interval.
2. On each subsequent failure, double the wait time.
3. Add random jitter (±10–20% of the interval) to desynchronize retries across clients.
4. Cap the maximum wait at a reasonable ceiling.
5. After a configurable number of attempts, stop retrying and alert your on-call team.

Example backoff schedule:

Use a maximum retry count

Set a hard limit on the number of retries (for example, 5 attempts). After that limit is reached without a successful response, stop retrying, record the failure, and alert your team. Continuing to retry indefinitely can mask a persistent issue and delay investigation.

Idempotency and safe retries

Before retrying a mutating request (such as creating a payment), check whether the original request may have been received and processed by Ripple despite returning an error. A network timeout, for example, does not mean the payment was not created.

Best practice: Use a client-assigned internalId or idempotency mechanism when creating payments. If you retry a payment creation request, include the same internalId as the original request. Ripple will return the existing payment if it was already created, preventing duplicate payments.

Handling authentication errors

401 Unauthorized (AUTH_001, AUTH_003)

A 401 error typically means your access token is expired or invalid. Access tokens have a 1-hour TTL.

Recommended handling:

1. Generate a new access token using your client_id and client_secret.
2. Retry the original request with the new token.
3. Do not cache tokens beyond their expires_in value.

For guidance on token generation and caching, see Authentication.

403 Forbidden (AUTH_002)

A 403 error means your token is valid but lacks the required scopes for the requested operation.

Recommended handling:

• Do not retry with the same token. A new token with the same credentials will have the same scopes.
• Review the required scopes for the operation in the API reference.
• Contact Ripple technical support if you believe your credentials should have the required permissions.

403 Unauthorized (AUTH_051)

AUTH_051 occurs when a request references a payment created by a different organization. This is a permanent error. Do not retry.

Handling payment failures

Payment failures are distinct from API errors. A payment failure occurs after a payment is created successfully (HTTP 201) but later transitions to a terminal state of FAILED, DECLINED, or RETURNED. These are not errors in the API response. They are paymentState values you observe when polling or receiving webhooks.

Terminal states

For a full list of payment failure codes and their descriptions, see API payment failures.

For background on payment states and the payment lifecycle, see Payment states.

What to log and monitor

Log the following fields from every error response:

• code — the specific error code; use this for alerting rules and dashboards
• type — the error category; use this to route to the correct handler
• status — the HTTP status code
• timestamp — the time the error occurred in the upstream system
• The API endpoint and HTTP method that returned the error
• Your request ID or correlation ID (if your integration generates one)

Alerting recommendations

Next steps

• For the complete list of error codes, descriptions, and HTTP statuses, see API error codes.
• For payment-specific failure codes, see API payment failures.
• For guidance on tracking payment state changes without polling, see Notification webhooks.
• To poll for payment updates instead of using webhooks, see Polling.
• For access token generation and caching details, see Authentication.
• For payment state definitions and lifecycle details, see Payment states.