Error Handling

Learn how to handle errors from the gleam.so API effectively.

Error Response Format

When an error occurs, the API will return a JSON response with error details. All error responses follow this format:

{
  "success": false,
  "error": {
    "code": string,     // Machine-readable error code
    "message": string,  // Human-readable error message
    "details"?: object  // Optional additional error details
  }
}

Common Error Types

400 Bad Request

The request was malformed or missing required fields.

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "templateSlug is required"
  }
}

401 Unauthorized

Authentication failed or API key is missing.

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

429 Too Many Requests

You have exceeded your rate limit.

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again in 30 seconds.",
    "retryAfter": 30
  }
}

For more details about rate limits, see our rate limits documentation.

PreviousGet Cached Image