Skip to main content

​
Common Errors

​
401 Unauthorized

  • Missing or invalid Authorization: Bearer header.
  • Key was deleted or never created.
  • Pasting the wrong value (e.g. your account password instead of an API key).

​
429 Too Many Requests

Two different cases — check the error message body:

​
Plan rate limit

You hit your per-window allowance, your weekly cap, or the per-minute burst limit.
  • The response tells you exactly when to retry: burst-limit 429s carry a Retry-After header and a code (rate_limit_exceeded, hourly_limit_exceeded, or token_limit_exceeded); quota exhaustion without credits returns 402 with a resets_at timestamp.
  • Wait for the window to slide, or for the weekly cap to reset on Monday 00:00 UTC.
  • Upgrade your plan or buy credits — credits extend your per-window allowance and weekly cap (they do not bypass the per-minute burst limit).

​
Temporary abuse/capacity throttle

Message: “Temporary rate limit applied due to high load”
  • Applied to this API key only — other keys and users are unaffected.
  • This is a rate reduction, not a block: the key keeps serving requests at a lower per-minute rate (shown in the max_rpm field) for a short period. You do not need to wait it out — retry shortly at the reduced rate.
  • Usually triggered by sustained, unusually high request volume from a single key.
  • Credits do not bypass this throttle.
  • Honor the Retry-After response header (or the retry_after_seconds body field) for when to retry. It is short — typically under a minute — and reflects the next retry slot under the reduced rate, not the remaining throttle duration.
  • Reduce request rate and concurrency; contact support if you believe this was applied in error.

​
529 Overloaded (capacity)

The requested model is temporarily at capacity.
  • The response includes a Retry-After header — honor it before retrying.
  • Openference recovers routes automatically when they become healthy again.
  • This does not consume your quota.

​
502 Upstream error

The provider serving your request returned an error after our retries. This is temporary, does not consume your quota, and usually resolves within moments. Retry or switch model.

​
403 model_not_available_in_zdr_mode

The API key has ZDR mode enabled, which restricts routing to the providers we classify as zero-data-retention, and the requested model has no ZDR route.
  • Disable ZDR mode on the key (dashboard → API key → edit), or
  • Choose a model served by a ZDR provider — GET /v1/models on that key already lists only those, or
  • Use a different key without ZDR mode.
Note that ZDR mode intentionally trades availability for retention: expect more 529 overload errors during upstream incidents because fewer routes are eligible.

​
Cursor Verify fails

  • Base URL must include the full path: https://api.openference.com/v1
  • Key must be valid and allowed to list the models Cursor is trying to verify.
See Verify issues.