Reference

Error Codes

All errors follow a consistent shape with a machine-readable code field. Parse code to handle errors programmatically.

HTTP	code	Meaning & Resolution
401	`API_KEY_EXPIRED`	Your API key has passed its expiration date. Generate a new one.
401	`INVALID_API_KEY`	API key is missing, does not exist, or has been revoked. Provide a valid key in the header.
403	`forbidden`	Valid key but insufficient permissions or your plan does not include this endpoint.
429	`LIMIT_EXCEEDED`	Your monthly API request limit has been reached. Upgrade your plan.
422	`validation_error`	Request body failed validation. Check `error.message` for the specific field errors.
429	`RATE_LIMIT_EXCEEDED`	Too many requests within a 1-minute window for your active plan.
500	`internal_error`	Unexpected server error. Safe to retry with exponential backoff. Report persistent issues via Contact.
503	`provider_unavailable`	The upstream AI provider is temporarily unavailable. Retry after a short delay or switch provider.

Error Response Shape

JSON

{
  "success": false,
  "request_id": "req_w8x2b1l9zp",
  "error": {
    "code":    "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit reached for free plan (10 requests/minute).",
    "details": []
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-04-12T18:00:00.000000Z"
  }
}

Handling Errors in Code

JavaScript

const res = await fetch('/api/v1/ai/content', { /* ... */ });
const data = await res.json();

if (!data.success) {
  switch (data.error.code) {
    case 'RATE_LIMIT_EXCEEDED':
      await sleep(60000); // back off for 1 minute
      break;
    case 'LIMIT_EXCEEDED':
      console.error('Monthly quota reached.');
      break;
    case 'INVALID_API_KEY':
      console.error('Invalid API key — check your credentials');
      break;
    default:
      console.error('API error:', data.error.message);
  }
}

Python

import requests, time

response = requests.post('/api/v1/ai/content', json={...}, headers={...})
data = response.json()

if not data['success']:
    code = data['error']['code']
    if code == 'RATE_LIMIT_EXCEEDED':
        time.sleep(60) # wait 1 min
    elif code == 'INVALID_API_KEY':
        raise ValueError('Invalid API key')
    else:
        raise Exception(f"API error: {data['error']['message']}")

Use exponential backoff for 5xx
For 500 and 503 errors, implement exponential backoff: wait 1s → 2s → 4s → 8s before retrying. Stop after 5 attempts.

Error Codes

Error Response Shape

Handling Errors in Code

Ready to build?