Skip to content

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 2xx range indicate success.
  • Codes in the 4xx range indicate client errors (e.g. invalid parameter, unauthorized access, quota exceeded).
  • Codes in the 5xx range indicate server errors.

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.

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.

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."]
}
}
}