Errors & Status Codes
The Akoole Developer Platform uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
- Codes in the
2xxrange indicate success. - Codes in the
4xxrange indicate client errors (e.g. invalid parameter, unauthorized access, quota exceeded). - Codes in the
5xxrange indicate server errors.
Standard Error Envelope
Section titled “Standard Error Envelope”All failure responses return a consistent JSON schema:
{ "status": "error", "error": { "code": "validation_failed", "message": "The given data was invalid.", "details": { "quantity": [ "The quantity must be an integer greater than 0." ] } }}| Field | Type | Description |
|---|---|---|
status |
string | Always "error". |
error.code |
string | A stable, machine-readable string code (e.g. validation_failed, unauthorized, not_found). |
error.message |
string | A human-readable description of what went wrong. |
error.details |
object | Optional dictionary with field-level validation errors or debugging metadata. |
HTTP Status Code Reference
Section titled “HTTP Status Code Reference”| Code | Reason Phrase | Meaning |
|---|---|---|
200 |
OK | The request was successful. |
201 |
Created | The resource (product, webhook, order) was successfully created. |
400 |
Bad Request | Malformed request syntax or unparseable JSON payload. |
401 |
Unauthorized | Missing, expired, or invalid API key. |
403 |
Forbidden | Your key lacks the required permission scope or your subscription plan does not allow API access. |
404 |
Not Found | The requested resource (product UUID, order UUID, webhook UUID) does not exist. |
422 |
Unprocessable Content | Semantic validation failure (e.g. invalid URL, missing required fields). |
429 |
Too Many Requests | Rate limit quota exceeded for the current 60-second window. |
500 |
Internal Server Error | Unexpected server condition. Our team is automatically alerted to 500 responses. |
Handling Validation Errors (422)
Section titled “Handling Validation Errors (422)”When submitting payloads (e.g. adjusting inventory or registering a webhook), field errors are grouped in error.details:
{ "status": "error", "error": { "code": "invalid_url", "message": "Webhook URL must use HTTPS.", "details": null }}If multiple fields fail validation simultaneously:
{ "status": "error", "error": { "code": "validation_failed", "message": "The given data was invalid.", "details": { "url": ["The url format is invalid."], "subscribed_events": ["The subscribed events field is required."] } }}