Error Codes

All errors return JSON with an error object:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry after 30 seconds.",
    "retry_after": 30
  }
}

HTTP Status Codes

Code	Meaning	Common Cause
400	Bad Request	Invalid JSON, missing required fields
401	Unauthorized	Missing or invalid API key / JWT token
403	Forbidden	Insufficient permissions for this resource
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate resource (entity already exists)
422	Validation Error	Invalid parameter values
429	Rate Limited	Too many requests — check Retry-After header
500	Server Error	Internal error — contact support
502	Bad Gateway	Service temporarily unavailable
503	Service Unavailable	Maintenance or overload

Error Codes

Code	Status	Description	Fix
INVALID_API_KEY	401	API key is invalid or expired	Generate a new key at /dashboard/api-keys
TOKEN_EXPIRED	401	JWT token has expired	Refresh the token
RATE_LIMITED	429	Request rate exceeded	Wait for retry_after seconds
CREDIT_EXHAUSTED	402	No API credits remaining	Upgrade plan or purchase credits
PROJECT_NOT_FOUND	404	Project ID doesn't exist	Check project ID
VECTOR_LIMIT_EXCEEDED	403	Vector storage limit reached	Upgrade plan
FILE_TOO_LARGE	413	File exceeds size limit	Check tier limits
VALIDATION_ERROR	422	Request body validation failed	Check parameter types and ranges

Rate Limit Headers

Every response includes rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1700000060
Retry-After: 30

Retry Strategy

import time
import requests

def api_call_with_retry(url, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, json=data, headers=HEADERS)
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 30))
            time.sleep(retry_after)
            continue
        return response
    raise Exception("Max retries exceeded")