Endpoints

Errors & rate limits

Errors always return a JSON envelope with a stable machine-readable code. Rate limits are enforced per API key, so one noisy environment cannot starve another.

Error envelope

json

{
  "error": {
    "message": "Rate limit reached for dheep-chat.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

Status codes

Code	Meaning	What to do
400	Bad request	Malformed JSON or an invalid parameter value.
401	Unauthorized	Missing, malformed, or unknown API key.
403	Forbidden	The key is disabled or lacks the required scope.
404	Not found	Unknown endpoint or model id.
422	Unprocessable	Valid JSON, but the request cannot be fulfilled.
429	Rate limited	Per-minute, per-day or token allowance exceeded.
500	Server error	Unexpected gateway failure. Safe to retry.
503	Unavailable	Capacity temporarily exhausted. Retry with backoff.

Rate limit headers

text

X-RateLimit-Limit-Requests: 300
X-RateLimit-Remaining-Requests: 284
X-RateLimit-Reset-Requests: 41s
X-RateLimit-Limit-Tokens: 5000000
X-RateLimit-Remaining-Tokens: 4211903

Read these on every response to shape your client-side concurrency instead of waiting for a 429.

Retry strategy

javascript

async function callWithRetry(body, attempt = 0) {
  const response = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
  if (response.status === 429 || response.status >= 500) {
    if (attempt >= 4) throw new Error("Dheep API unavailable");
    const delay = Math.min(8000, 2 ** attempt * 500) + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, delay));
    return callWithRetry(body, attempt + 1);
  }
  return response.json();
}

Never retry a 400, 401 or 403 — those require a code or key change.