Errors

When an error occurs, the API returns an appropriate HTTP status code along with a JSON error object containing details about the issue.

Error Response Format

All error responses follow this structure:

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "details": "Field 'name' is required",
    "request_id": "req-550e8400-e29b-41d4-a716-446655440000"
  }
}

Error Fields

code - HTTP status code

message - Human-readable error message

details - Additional details about the error (optional)

request_id - Unique identifier for debugging

HTTP Status Codes

Code	Name	Description
400	Bad Request	The request was malformed or missing required parameters.
401	Unauthorized	Authentication credentials are missing or invalid.
403	Forbidden	You don't have permission to access this resource.
404	Not Found	The requested resource doesn't exist.
409	Conflict	The request conflicts with the current state of the resource.
422	Unprocessable Entity	The request was well-formed but contains invalid data.
429	Too Many Requests	You've exceeded the rate limit. Retry after the specified time.
500	Internal Server Error	An unexpected error occurred on the server.
503	Service Unavailable	The service is temporarily unavailable. Try again later.

Handling Errors

When handling errors, check the HTTP status code first, then parse the error response body for more details. Always log the request_id to help with debugging and support requests.