Errors & Rate Limits

Understand failure modes so you can retry safely and surface clear messages to users.

Error envelope

{
  "success": false,
  "error": "Error message",
  "details": {
    "tokensRequired": 120,
    "remainingTokens": 40
  }
}

details is optional and varies by error type.

HTTP status codes

Status	Meaning	Typical cause
200	Success	Request completed
400	Bad Request	Missing prompt/model, unsupported provider, invalid type
401	Unauthorized	Missing, invalid, or expired API key
402	Payment Required	No active subscription or insufficient tokens
403	Forbidden	Provider/model not allowed for this key
429	Too Many Requests	Hourly rate limit exceeded
500	Server Error	Unexpected failure during generation
503	Unavailable	Pricing/config temporarily unavailable

Common error messages

Missing API key

{
  "success": false,
  "error": "API key is required. Please provide it in X-API-Key header or Authorization header."
}

Invalid parameters

{
  "success": false,
  "error": "Prompt is required and must be a string"
}

{
  "success": false,
  "error": "Model is required and must be a string"
}

{
  "success": false,
  "error": "Model not found or unavailable"
}

Insufficient tokens

{
  "success": false,
  "error": "Insufficient tokens for this operation",
  "details": {
    "tokensRequired": 500,
    "remainingTokens": 120
  }
}

No subscription

{
  "success": false,
  "error": "No active subscription found. Please purchase a subscription to use this service."
}

Rate limited key

{
  "success": false,
  "error": "Rate limit exceeded",
  "details": {
    "isRateLimited": true,
    "remainingHourlyRequests": 0
  }
}

Rate limits

Each API key can define rate_limit_per_hour and max_tokens_per_request.

Inspect live values via GET /api/external/ai:

Field	Description
api_key_info.rate_limit_per_hour	Max requests per hour
api_key_info.remaining_hourly_requests	Remaining requests in the current window
api_key_info.max_tokens_per_request	Hard cap per call

Retry guidance

Status	Retry?	Strategy
429	Yes	Exponential backoff; respect hourly window
500 / 503	Yes	Retry with jitter; fail after a few attempts
400 / 401 / 403	No	Fix request or key configuration
402	No	Top up tokens or renew subscription

Client-side pattern

async function callAbzarAI(body, apiKey) {
  const res = await fetch("https://abzar-ai.com/api/external/ai", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": apiKey
    },
    body: JSON.stringify(body)
  })

  const json = await res.json()

  if (!res.ok || !json.success) {
    const error = new Error(json.error || "Request failed")
    error.status = res.status
    error.details = json.details
    throw error
  }

  return json.data
}