Skip to main content

​
Overview

All API endpoints return consistent error responses with standard HTTP status codes. When an error occurs, the response will include a JSON body with details about the error.

​
Error Response Format

All error responses follow this format: 
{
  "error": {
    "code": "error_code",
    "message": "Human-readable error description",
    "details": {} // Optional: Additional error details
  }
}

​
Common Error Codes

Status CodeError TypeDescription
400Bad RequestInvalid request parameters or malformed request body. Check that all required fields are provided and properly formatted.
401UnauthorizedInvalid or missing API key. Ensure your x-api-key header is present and contains a valid API key.
403ForbiddenYou don’t have permission to access this resource. This may occur if your API key doesn’t have the necessary permissions.
404Not FoundThe requested resource doesn’t exist. Verify that the resource ID (e.g., session_id) is correct.
409ConflictThe request conflicts with the current state of the resource. For example, trying to create a resource that already exists.
422Unprocessable EntityThe request is well-formed but contains semantic errors. Check that your request data meets all validation requirements.
429Too Many RequestsRate limit exceeded. You’ve made too many requests in a short period. Please wait before retrying.
500Internal Server ErrorAn unexpected error occurred on the server. If this persists, please contact support.
502Bad GatewayThe server received an invalid response from an upstream server. This is usually temporary.
503Service UnavailableThe service is temporarily unavailable due to maintenance or overload. Please try again later.

​
Rate Limiting

When rate limited (429 status code), the response will include these headers:
  • X-RateLimit-Limit: The maximum number of requests allowed
  • X-RateLimit-Remaining: The number of requests remaining in the current window
  • X-RateLimit-Reset: The time when the rate limit window resets (Unix timestamp)
  • Retry-After: The number of seconds to wait before making another request

​
Example Error Responses

​
Bad Request (400)

{
  "error": {
    "code": "invalid_parameters",
    "message": "The 'role_id' field is required",
    "details": {
      "field": "role_id",
      "requirement": "required"
    }
  }
}

​
Unauthorized (401)

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked"
  }
}

​
Not Found (404)

{
  "error": {
    "code": "session_not_found",
    "message": "Session with ID '123' does not exist"
  }
}

​
Rate Limited (429)

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded. Please wait 60 seconds before retrying.",
    "details": {
      "limit": 100,
      "window": "1 minute",
      "retry_after": 60
    }
  }
}

​
Internal Server Error (500)

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again or contact support if the issue persists.",
    "details": {
      "request_id": "req_abc123xyz"
    }
  }
}

​
Best Practices

  1. Always check the status code before processing the response body
  2. Implement exponential backoff for rate limit errors (429)
  3. Log error details including the request_id when available for debugging
  4. Handle errors gracefully in your application with appropriate user messaging
  5. Don’t retry 4xx errors immediately as they typically indicate client-side issues that need to be fixed