Errors
Every error is a JSON object with a stable code, a message and a request_id. The full list of codes, what causes each and whether to retry.
Every error is one JSON object with a stable code to branch on, a human-readable message, and a request_id to quote to support. Fix and resend 4xx errors; retry only 429 after Retry-After and 5xx with backoff.
Error shape
Every error response is JSON with a single error object:
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Validation failed",
"request_id": "8f3c2a1e-4b6d-4e7f-9a0b-1c2d3e4f5a6b",
"fields": {
"to": "range exceeds 31 days"
}
}
}| Field | Description |
|---|---|
code | Stable, machine-readable code. Branch on this, not on message. |
message | Human-readable summary. May change; do not parse it. |
request_id | Identifier of the request. Include it when contacting Octane support. |
fields | Only on VALIDATION_FAILED: a map of parameter name to problem. |
Responses produced at the edge (IP_NOT_ALLOWED, RATE_LIMITED) contain only code.
Error codes
| Status | Code | Meaning | What to do |
|---|---|---|---|
400 | VALIDATION_FAILED | A parameter is missing, malformed or out of range. | Read fields, fix the request. Do not retry unchanged. |
401 | INVALID_API_KEY | The key is missing, unknown or switched off. | Check the X-API-Key header. If the key was switched off, obtain a new key from Octane. Do not retry unchanged. |
403 | IP_NOT_ALLOWED | The source IP is not on the key's allow-list. | Send the IP to Octane to be added. Do not retry until it is. |
403 | API_INTEGRATION_NOT_ENABLED | API integration is switched off on your account. | Contact your Octane account manager. |
403 | NO_ACTIVE_CHARGING_PROFILE | Your account has no active, unexpired charging profile. | Contact your Octane account manager to renew. |
403 | EDGE_NOT_ENFORCED | An Octane-side configuration problem. | Contact Octane support with the request_id. |
404 | CORPORATE_NOT_FOUND | A corporate_id is not part of your account. | Check the id. |
404 | CORPORATE_GROUP_NOT_FOUND | The corporate_group_id is not part of your account. | Check the id. |
429 | RATE_LIMITED | More than 60 requests in the current minute. | Wait for Retry-After seconds and retry. See Rate limit. |
5xx | Temporary server error. | Retry with exponential backoff. |
Which errors should I retry?
| Status | Retry? |
|---|---|
400, 401, 403, 404 | No. Fix the cause first. |
429 | Yes, after Retry-After seconds. |
5xx, network timeout | Yes, with exponential backoff and a cap (for example 5 attempts starting at 2 seconds). |
Validation errors on the transactions endpoint typically name one of these problems in fields:
| Parameter | Typical problems |
|---|---|
from, to | missing, not ISO 8601, to before from, range exceeds 31 days |
limit | not an integer, below 1, above 100 |
status | value other than CONFIRMED or EXTERNAL |
corporate_id | not an integer or comma-separated list of integers |
cursor | malformed |