API errors

An error answers with an HTTP status and a body in the problem details format (application/problem+json, RFC 9457). Branch on code, which never changes; title and detail are written for people and can.

{
  "type": "https://ranqo.ai/docs/api/errors#rate_limited",
  "title": "Rate limited",
  "status": 429,
  "detail": "This key is limited to 60 requests a minute.",
  "code": "rate_limited",
  "request_id": "req_7kq2mzd4wax3hrn5tvbfc6jp",
  "retry_after_seconds": 17
}

• type links to the code's section on this page.
• detail says what went wrong and, where there is something to do, what to do.
• request_id is also in the X-Request-Id header of every response. Quote it when you contact support.
• errors, on an invalid parameter, lists each parameter at fault with a message.

Request errors#

invalid_parameter#

A query parameter has a value the endpoint does not accept: an unknown engine or category, a date that is not a calendar date, a window longer than allowed, a time zone that is not an IANA name, or period sent together with start_date. The errors list names each parameter and why. Fix the value and send the request again.

unknown_parameter#

The request sent a query parameter the endpoint does not take. Parameters are checked strictly, so a misspelled one is reported rather than silently ignored. Each reference page lists the parameters its endpoint takes.

invalid_cursor#

The cursor does not belong to this request: it is malformed, or it was issued for other filters, another endpoint, or a window or board that has moved on since: a prompt's answers over a preset period whose day has turned, or over a window that held no run and now holds one, and Outreach targets after the board was refreshed. Start again from the first page, without a cursor. See Pagination.

api_key_in_url#

The request address contains an API key. Send the key only in the Authorization header. If a real key was sent, revoke it in Settings and create another: an address can end up in logs you do not control.

Key and plan errors#

missing_api_key#

The request has no Authorization header, or an empty one. Send Authorization: Bearer followed by your key.

invalid_api_key#

The header does not hold a well-formed Ranqo key, or no key matches it. Check that the whole key was copied. See Authentication.

api_key_revoked#

The key was revoked in Settings. Create another.

api_key_expired#

The key has passed the expiry chosen when it was created. Create another.

api_key_orphaned#

The account that owns the key has since joined another team, and keys belong to account owners. Ask the team's owner to create a key in their Settings.

plan_upgrade_required#

The account's plan does not include API access. It is included on Pro and above.

subscription_inactive#

The account's trial or subscription has ended. Choose a plan to use the API again.

Missing things#

not_found#

The brand, run, prompt, audit or recommendation does not exist, or this key cannot read it: it belongs to another account, the brand was removed, or the key is restricted to other brands. The API answers all of these alike, so it never tells a caller whether something it cannot read exists.

route_not_found#

There is no endpoint at this path. Check the path against the reference; every path starts with /v1.

method_not_allowed#

The API is read-only: every endpoint answers GET only.

Limits and outages#

rate_limited#

The key has used its requests for this minute, or has failed authentication too often. Wait the seconds in the Retry-After header, or in retry_after_seconds, then retry. See Rate limits.

internal_error#

Something failed on Ranqo's side. Retry after a short wait; if it keeps happening, contact support with the request_id.

service_unavailable#

A service the API depends on is briefly unavailable, and the API refuses the request rather than serve it without counting it. Retry after the seconds in the Retry-After header.