Error Responses

All API errors follow a standard JSON format returned by the API gateway error-handling middleware.

Error Format

{
  "error": "NOT_FOUND",
  "code": "NOT_FOUND",
  "message": "The requested resource was not found",
  "details": {},
  "request_id": "req-abc123-def456",
  "timestamp": "2026-02-19T15:30:00Z"
}

Field	Type	Description
error	string	Machine-readable error code
code	string	Error code (same as error)
message	string	Human-readable description
details	object	Additional context (optional, may contain field-level errors)
request_id	string	Unique request identifier for debugging
timestamp	string	ISO 8601 timestamp

HTTP Status Codes

Status	Code	Description
400	BAD_REQUEST	Malformed request body or parameters
400	VALIDATION_ERROR	Request validation failed
400	INVALID_JSON	JSON parsing error
401	UNAUTHORIZED	Missing or invalid JWT token
401	INVALID_TOKEN	Token is malformed
401	TOKEN_EXPIRED	JWT token has expired
401	INVALID_CREDENTIALS	Wrong email/password
403	FORBIDDEN	User lacks required permissions
404	NOT_FOUND	Resource does not exist
405	METHOD_NOT_ALLOWED	HTTP method not supported
409	CONFLICT	Resource already exists
413	CONTENT_TOO_LARGE	Request body exceeds size limit
429	TOO_MANY_REQUESTS	Rate limit exceeded
500	INTERNAL_SERVER_ERROR	Unexpected server error
502	BAD_GATEWAY	Upstream service unavailable
503	SERVICE_UNAVAILABLE	Service temporarily unavailable
504	TIMEOUT	Request timed out

Business Logic Errors

Some operations return domain-specific error codes:

Code	Description
INSUFFICIENT_FUNDS	Payment amount exceeds available balance
ORDER_NOT_CANCELABLE	Order has already been completed
TABLE_OCCUPIED	Table is already in use
MENU_ITEM_UNAVAILABLE	Item is 86'd (out of stock)
DUPLICATE_ENTRY	Record with same key already exists
RESOURCE_LOCKED	Resource is locked by another operation

Validation Errors

When a request fails validation, the details field contains field-level errors:

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": {
    "email": "must be a valid email address",
    "password": "must be at least 8 characters"
  },
  "request_id": "req-abc123",
  "timestamp": "2026-02-19T15:30:00Z"
}

Rate Limiting

When rate-limited (HTTP 429), the response includes retry headers:

Retry-After: 1
X-RateLimit-Limit: 80
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708358400

The default rate limit is 80 requests per second per IP address.

Handling Errors

import requests

response = requests.post(
    "https://dev.api.olympuscloud.ai/v1/commerce/orders",
    headers={"Authorization": f"Bearer {token}"},
    json=order_data,
)

if response.status_code == 200:
    order = response.json()
elif response.status_code == 401:
    # Token expired — refresh and retry
    new_token = refresh_token(refresh)
    # retry...
elif response.status_code == 429:
    # Rate limited — wait and retry
    retry_after = int(response.headers.get("Retry-After", 1))
    time.sleep(retry_after)
    # retry...
else:
    error = response.json()
    print(f"Error {error['code']}: {error['message']}")
    print(f"Request ID: {error['request_id']}")