2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with OneBalance’s servers.
HTTP Status Codes
| Status Code | Type | Description |
|---|---|---|
| 200 | OK | Everything worked as expected. |
| 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. |
| 401 | Unauthorized | No valid API key provided. |
| 402 | Request Failed | The parameters were valid but the request failed. |
| 403 | Forbidden | The API key doesn’t have permissions to perform the request. |
| 404 | Not Found | The requested resource doesn’t exist. |
| 429 | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
| 500, 502, 503, 504 | Server Errors | Something went wrong on OneBalance’s end. |
Quote Execution Failures
While HTTP status codes indicate API request success/failure, quote executions can fail for business logic reasons even when the API request succeeds (returns 200). When a quote execution fails, it will be marked asREFUNDED and include a failReason field explaining why.
Understanding the Difference
- HTTP Errors (4xx/5xx): Issues with the API request itself (authentication, malformed requests, server errors)
- Execution Failures: Business logic failures where the quote couldn’t be completed (insufficient balance, slippage, etc.)
For a complete list of execution failure codes with detailed explanations and troubleshooting steps, see Error Codes.
Error Response Format
Both400 and 500 level errors return a JSON object in the response body, containing specific attributes detailing the error.
| Name | Type | Description |
|---|---|---|
| error | string | A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be “not_found.” |
| message | string | A message providing additional information about the error, including details to help resolve it when possible. |
| statusCode | number | HTTP status code. |
| timestamp | string | Timestamp of the error. |
| path | string | Path of the request that caused the error. |
Example Error Response
HTTP/1.1 401 UnauthorizedUnauthorized
Error Handling Best Practices
- Always check for error responses in your API integrations
- Use the
statusCodeto determine the type of error - Look at the
messagefield for specific details on how to resolve the issue - For refunded quotes, check the
failReasonfield and implement appropriate retry logic - Include the error
idwhen using the Intercom chat widget or contacting support about any API issues - See Error Codes for handling specific execution failure scenarios