Errors & rate limits

The Workspace API uses conventional HTTP status codes and a consistent JSON error shape.

Error response shape

Errors return a JSON body with an error message:

{ "error": "This model is not available on your current plan." }

Status codes

Code	Meaning	What to do
200	Success	—
201	Created	Resource was created.
400	Bad request	Check required fields and types.
401	Unauthorized	Missing, malformed, or revoked API key.
403	Forbidden	Action not allowed (e.g. a plan or capability restriction).
404	Not found	The resource ID doesn’t exist in this workspace/project.
409	Conflict	The resource already exists (e.g. a tracked competitor).
413	Payload too large	Upload exceeds your storage quota or size limits.
429	Too many requests	You hit a rate limit — back off and retry.
5xx	Server error	Transient; retry with backoff.

Note

A 403 typically means a plan or quota restriction (for example, a model not included in your plan, or a daily quota reached) rather than an authentication problem. The error message explains which.

Rate limits

The API shares your plan’s rate limits and daily quotas. When you exceed a limit, you receive 429 with a Retry-After header indicating how many seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{ "error": "Too many requests. Please slow down." }

Handling 429 with backoff

Node.js — retry on 429

async function callWithRetry(url, options, maxRetries = 4) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429 || attempt >= maxRetries) return res;
    const retryAfter = Number(res.headers.get("Retry-After")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
  }
}

Best practices

• Back off on 429 using the Retry-After value; add jitter for many parallel workers.
• Don’t hammer — spread bulk work over time rather than bursting.
• Check credits — a 403 about credits or quotas means you should top up or upgrade, not retry.
• Fail safe — treat 5xx as transient and retry idempotent reads; be careful retrying creates.
• Log the error message — it’s designed to be human‑readable and actionable.

Related

Usage & limits The limits behind these codes.

Authentication Avoid 401s with correct keys.

API overview Conventions and base URL.