Error Response Structure
All errors follow a consistent envelope regardless of the HTTP status code. This makes it straightforward to write a single error-handling function in your integration layer.| Field | Type | Description |
|---|---|---|
code | string | Machine-readable error identifier. Use this in your error-handling logic. |
message | string | Human-readable explanation. Surface this in logs and support tickets, not in end-user UI. |
field | string | null | The request field that caused the error, using dot notation. Present only for validation errors. |
docs_url | string | Direct link to this page for the relevant error category. |
HTTP Status Codes
RemitFlex uses a standard subset of HTTP status codes. Each maps to a category of problem with a distinct resolution path.| Status | Meaning | Typical cause |
|---|---|---|
400 Bad Request | Validation error | Malformed request body or invalid field value |
401 Unauthorized | Authentication failure | Missing, expired, or malformed API key |
402 Payment Required | Insufficient funds or limit | Account balance too low or payment cap exceeded |
403 Forbidden | Action not permitted | Account tier, permission scope, or compliance block |
404 Not Found | Resource missing | Invalid payment ID, quote ID, or recipient ID |
409 Conflict | Duplicate request | Idempotency key already associated with a completed request |
422 Unprocessable Entity | Business logic error | Corridor unavailable, quote expired, or unsupported flow |
429 Too Many Requests | Rate limit exceeded | Request volume exceeded your account’s rate limit |
500 Internal Server Error | RemitFlex server fault | Transient infrastructure issue; safe to retry with backoff |
Error Code Reference
The sections below group every error code by category. Each entry includes the HTTP status it accompanies, a description of the root cause, and the recommended resolution.Authentication Errors
Authentication Errors
Authentication errors indicate a problem with how your request is identifying itself to the API. These are almost always configuration issues rather than transient faults, so retrying without fixing the root cause will not help.
| Code | HTTP Status | Description | Resolution |
|---|---|---|---|
UNAUTHORIZED | 401 | The Authorization header is missing, malformed, or contains an invalid API key. | Verify the key is correctly formatted as Bearer rf_test_... or Bearer rf_live_... and that no characters were truncated. |
API_KEY_REVOKED | 401 | The API key was explicitly revoked from the Dashboard or via the API Keys management endpoint. | Generate a new key under Settings → API Keys and update your environment configuration. |
INSUFFICIENT_PERMISSIONS | 403 | The API key is valid but does not have the scope required to perform this action (e.g., a read-only key attempting to create a payment). | Issue a new key with the appropriate permission scopes, or contact your account administrator. |
RemitFlex API keys do not expire on a time basis, but they are invalidated immediately if revoked. If you rotate keys as part of your security policy, ensure your deployment pipeline updates the key atomically to avoid
UNAUTHORIZED errors during the rotation window.Payment Errors
Payment Errors
Payment errors arise during the creation, processing, or delivery of a payment or conversion. Some are recoverable by correcting input; others indicate a terminal state for that specific payment attempt.
| Code | HTTP Status | Description | Resolution |
|---|---|---|---|
INVALID_AMOUNT | 400 | The requested amount is below the corridor minimum or above the corridor maximum. | Query GET /corridors/{id} for the current min/max limits and adjust the amount accordingly. |
INVALID_CURRENCY | 400 | The currency code is not recognized or is not supported in the requested direction. | Check the Supported Currencies page and ensure you are using the correct uppercase symbol or ISO 4217 code. |
INVALID_RECIPIENT | 400 | One or more recipient fields — such as bank account number, routing number, or mobile wallet ID — are invalid for the destination country. | Re-validate recipient details against the field requirements in GET /corridors/{id}/recipient-fields. |
CORRIDOR_UNAVAILABLE | 422 | The source-to-destination corridor is not currently active. This may be a temporary suspension or a permanently unsupported route. | Check the RemitFlex Status Page for corridor outages. If the corridor should be supported, contact support. |
QUOTE_EXPIRED | 422 | The conversion quote referenced by quote_id has passed its validity window (typically 30 seconds). | Fetch a fresh quote via POST /quotes and use the new quote_id in your payment request. |
INSUFFICIENT_FUNDS | 402 | Your RemitFlex wallet balance for the source currency is too low to cover the payment amount plus fees. | Top up your balance via the Dashboard or the POST /funding endpoint, then retry the request. |
PAYMENT_CANCELLED | 409 | The payment was previously cancelled and cannot be resubmitted with the same ID. | Create a new payment with a new Idempotency-Key if you still need to complete the transfer. |
RECIPIENT_BANK_REJECTED | 422 | The recipient’s bank returned a rejection after RemitFlex submitted the payout. This is terminal for the payment. | Contact the recipient to verify their account details, then create a new payment with corrected recipient information. |
Compliance Errors
Compliance Errors
Compliance errors are raised by RemitFlex’s real-time sanctions screening, KYC/KYB verification checks, and transaction limit enforcement. These errors are not safe to retry without first resolving the underlying compliance issue.
| Code | HTTP Status | Description | Resolution |
|---|---|---|---|
KYC_REQUIRED | 403 | The sending user has not completed identity verification. This is required before any payment can be initiated. | Direct the user to your KYC flow. RemitFlex provides a hosted verification link via POST /kyc/sessions. |
KYB_REQUIRED | 403 | The transaction size or destination requires business verification (KYB) that has not been completed for this account. | Complete KYB from Dashboard → Settings → Verification or via the KYB API. |
LIMIT_EXCEEDED | 402 | The transaction would cause the account’s daily or monthly volume limit to be exceeded. | Wait until the limit resets (limits reset at 00:00 UTC), or contact your account manager to request a limit increase. |
COMPLIANCE_REVIEW | 403 | The transaction has been flagged for manual compliance review and cannot be processed automatically. | This review typically completes within one to two business days. You will receive a webhook event (compliance.review.completed) when it resolves. |
Rate Limit Errors
Rate Limit Errors
RemitFlex enforces per-key rate limits to protect platform stability. Rate limit errors are always transient — the correct response is to slow down and retry after the window resets.
The
| Code | HTTP Status | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | 429 | Your API key has exceeded the allowed number of requests within the current time window. | Check the Retry-After response header for the number of seconds to wait before sending the next request. Implement exponential backoff for sustained high-volume flows. |
429 response includes headers to help you manage pacing:| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed per minute for this key |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp at which the window resets |
Retry-After | Seconds to wait before retrying |
Default rate limits are 300 requests per minute for live keys and 60 requests per minute for sandbox keys. Enterprise accounts have elevated limits configured on their contract. Contact your account manager if your use case requires higher throughput.
Idempotency
RemitFlex supports idempotent requests for all state-mutating endpoints (POST, PATCH, DELETE). Idempotency lets you safely retry a request — for example, after a network timeout — without risking duplicate payments or double charges.
To use idempotency, include a unique Idempotency-Key header on every mutating request:
- Generate a new, unique key for each intended payment. A UUID v4 or ULID is a reliable choice.
- Reuse the same key when retrying a request that received no response or a
5xxerror. - Idempotency keys are scoped to your API key and expire after 24 hours.
- If you reuse a key with a different request body, RemitFlex returns
409 Conflictwith codePAYMENT_CANCELLEDto protect against accidental misuse.
If a request with a given idempotency key is still being processed (e.g., the original request is in flight), subsequent requests with the same key will return
409 Conflict. Poll GET /payments/{id} for the status of the in-flight payment rather than retrying the creation request.Retry Strategy
Not all errors are worth retrying. Retrying a permanent error wastes resources and delays detecting a configuration problem. Use this table to decide whether to retry, fix and retry, or escalate.| Error type | Examples | Retryable? | Recommended action |
|---|---|---|---|
| Transient server fault | 500 Internal Server Error | ✅ Yes | Retry with exponential backoff: 1s → 2s → 4s → 8s (max 3 attempts) |
| Rate limit | RATE_LIMIT_EXCEEDED | ✅ Yes | Wait for Retry-After seconds, then retry |
| Quote expired | QUOTE_EXPIRED | ✅ Yes | Re-fetch a new quote, then retry the payment |
| Insufficient funds | INSUFFICIENT_FUNDS | ✅ After fix | Top up balance, then retry |
| Validation error | INVALID_AMOUNT, INVALID_RECIPIENT | ✅ After fix | Correct the offending field(s), then retry |
| Authentication | UNAUTHORIZED, API_KEY_REVOKED | ❌ No | Fix credentials configuration; retrying will continue to fail |
| Compliance block | SANCTIONS_MATCH, KYC_REQUIRED | ❌ No | Resolve compliance issue through the appropriate channel |
| Terminal payment state | PAYMENT_CANCELLED, RECIPIENT_BANK_REJECTED | ❌ No | Create a new payment; the original cannot be resumed |
| Corridor unavailable | CORRIDOR_UNAVAILABLE | ⚠️ Sometimes | Check status page; retry only after corridor is confirmed restored |