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
statusCode
to determine the type of error - Look at the
message
field for specific details on how to resolve the issue - For refunded quotes, check the
failReason
field and implement appropriate retry logic - Include the error
id
when using the Intercom chat widget or contacting support about any API issues - See Error Codes for handling specific execution failure scenarios