Error Handling

Authentication Errors (401)

These occur when your API key is invalid, missing, or revoked. The error message clearly indicates a failed authentication.

{
  "code": "authentication_failed",
  "message": "Invalid or missing API key"
}

Permission Errors (403)

Triggered when your API key does not have access to the requested resource or feature. Check your subscription tier and dashboard permissions.

{
  "code": "insufficient_permissions",
  "message": "API key doesn't have required permissions"
}

Request Errors (400)

Occur when required fields are missing, parameter types are incorrect, or the request format is invalid.

{
  "code": "invalid_request",
  "message": "Missing required field: text"
}

Validation Errors (422)

Raised when input values are outside acceptable ranges, such as an invalid compression ratio. The error message specifies the valid range or expected format.

{
  "code": "validation_error",
  "message": "Compression ratio must be between 0.3 and 0.7"
}

Rate Limit Errors (429)

Occur when too many requests are made in a short time. The message includes details like limit type and reset time. Implement exponential backoff or batching to mitigate.

{
  "code": "rate_limit_exceeded",
  "message": "RPM limit exceeded",
  "details": {
    "limit_type": "rpm",
    "reset_at": 1640000000
  }
}

Server Errors (500)

Internal server errors happen when something unexpected occurs on the API side. Retry the request or contact support if persistent.

{
  "code": "internal_error",
  "message": "An unexpected error occurred"
}