Error Codes

Hyperrails API Response Codes

Hyperrails uses standard HTTP response codes to communicate the outcome of API requests. Always inspect both the HTTP status code and the response body to fully understand what happened.

Success (2xx)

200 OK
The request was processed successfully.
⚠️ Always inspect the response payload to confirm the actual transaction state.
201 Created
A new resource was successfully created (e.g., transactions, accounts, or configurations).

Client Errors (4xx)

400 Bad Request
The request is malformed or missing required parameters.
✔️ Validate request payloads and data types.
401 Unauthorized
Authentication failed due to a missing or invalid API key.
✔️ Ensure your API key is included in the Authorization header.
403 Forbidden
The API key does not have permission to perform the requested action.
✔️ Verify the key’s scope or assigned role.
404 Not Found
The requested resource does not exist or the endpoint is incorrect.
429 Too Many Requests
Rate limit exceeded.
✔️ Implement retry logic with exponential backoff.

Server Errors (5xx)

500, 502, 503, 504
These indicate internal server errors on Hyperrails’s infrastructure.
✔️ Treat the outcome as inconclusive and retry later.
✔️ If persistent, contact support.

Error Handling Best Practices

Beyond HTTP status codes, Hyperrails responses may include structured error objects with additional context such as error type, message, and resolution hints.

General Guidelines

Do Not Assume Outcomes
Network or timeout errors may leave the transaction state unknown.
Rely on Webhooks
Webhooks provide authoritative confirmation of transaction outcomes and should be treated as the source of truth.

Common Error Types

Error Type	Description	Recommended Action
Invalid Request Error	Request parameters are invalid, missing, or incorrectly formatted.	Review endpoint documentation and fix request payloads.
Authentication Error	API key is missing, invalid, or inactive.	Verify the API key and authorization headers.
Permission Error	API key lacks the required permissions.	Use a key with appropriate access or update role permissions.
Rate Limit Error	Too many requests sent within a short timeframe.	Implement retries with backoff or request higher limits.
Connection Error	Temporary network or connectivity issue.	Retry safely and rely on webhooks for final status.
Server Error	Internal error on Hyperrails’s side.	Retry later and monitor webhook events.

Error Code Reference

Every 4xx/5xx response body includes a machine-readable code field. Branch on code, not on the human-readable message (message text may change; code will not).

`code`	HTTP status	Meaning	Recommended action
`INSUFFICIENT_BALANCE`	400	Account/wallet balance is below the requested amount plus fees.	Check balance via `GET /partners/balances` before retrying.
`INVALID_BANK_CODE`	400	Bank code doesn’t match a supported bank for the currency.	Validate against `GET /transfers/banks/{currency}`.
`INVALID_ACCOUNT_NUMBER`	400	Account number fails format validation for the country.	Re-check format (10 digits for NGN).
`NAME_MISMATCH`	400	Provided account name doesn’t match bank records.	Re-resolve via `GET /transfers/resolve-account` and use the returned name.
`DUPLICATE_REFERENCE`	400	The idempotency `reference` was already used.	Reuse is safe — fetch the original result instead of retrying with a new reference.
`INVALID_ADDRESS`	400	Destination blockchain address is malformed.	Validate as a checksummed EVM address before sending.
`INVALID_CURRENCY_PAIR`	400	Requested currency pair isn’t supported.	Check Supported Currencies.
`AMOUNT_TOO_LOW`	422	Amount is below the endpoint’s minimum.	See per-endpoint minimums in the API reference.
`WALLET_NOT_FOUND`	404	No active wallet exists for this partner/currency.	Create or fund a wallet first.
`RATE_UNAVAILABLE`	— (stream error event)	No liquidity provider could quote this pair right now.	Retry, or fall back to `GET /partners/rates`.
`SERVICE_UNAVAILABLE`	503	Upstream bank/chain provider is temporarily down.	Retry with backoff; rely on webhooks for final state.

By properly handling these errors and relying on webhooks for final state confirmation, you can build resilient, fault-tolerant integrations with the Hyperrails API.

API Reference

ISO20022 Compliance

Wallets and Balances

Rates

Exchange

Payout

Dynamic Accounts

Marketplace

Hyperrails API Response Codes

Success (2xx)

Client Errors (4xx)

Server Errors (5xx)

Error Handling Best Practices

General Guidelines

Common Error Types

Error Code Reference

​Hyperrails API Response Codes

​Success (2xx)

​Client Errors (4xx)

​Server Errors (5xx)

​Error Handling Best Practices

​General Guidelines

​Common Error Types

​Error Code Reference

Hyperrails API Response Codes

Success (2xx)

Client Errors (4xx)

Server Errors (5xx)

Error Handling Best Practices

General Guidelines

Common Error Types

Error Code Reference