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 for that specific key.
  • 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.

​
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.