Skip to main content
Version: Next

Errors

Format​

Every error has the same shape:

{ "error": { "code": "rate_limited", "message": "Too many requests.", "resetsAt": "2026-11-02T15:31:00Z" } }

Some errors add fields. Each one is optional and appears only on the errors it belongs to. The list is not closed: an error can also carry fields from the check that refused the call (for example required, balance or plan on a 402), so ignore members you do not know:

FieldTypeOn
resetsAtISO date-time429, and 402 cap refusals: when you can try again
retryAfterSecondsinteger429: the same wait as Retry-After
windowstring402 cap refusals: daily, weekly or monthly
capCredits, usedCredits, requiredCreditsnumber402 cap refusals
requiredScopesarray of strings403 insufficient_scope
limit, used, bucket, windowMinutes, busyinteger, string, booleanrun-limit 429
detailsobject of field name to messages400 invalid_request: what was wrong, per field

A missing or unusable key on any /api/public/v1 route answers 401 with api_key_required in this shape, with a WWW-Authenticate: Bearer header. A body or query value that cannot be read (an empty body, bad JSON, ?limit=abc) answers 400 invalid_request with details. Every response, successful or not, has an X-Request-Id header. Include it when you contact support.

Codes​

CodeMeaningWhat to do
api_key_requiredNo API key was sent, or a dashboard session was used on the APISend Authorization: Bearer rbk_...
invalid_api_keyThe key is unknown or wrongCheck the secret; create a new key
api_key_revokedThe key was revokedCreate a new key
api_key_expiredThe key passed its expiryCreate a new key
api_key_inactiveThe key's service account or membership is gone, or a queued request was refused because the key is no longer activeCreate a new key and retry
API_KEY_INACTIVERun failure code: the key was revoked or expired while its run was goingCreate a new key and start the run again
insufficient_scopeThe key lacks the scope this call needsCreate a key with the scope
scope_not_declaredThe call has no scope set up and is refusedContact support with the X-Request-Id
api_key_scopeA key was used on a dashboard routeUse the /api/public/v1 routes
rate_limitedToo many requestsWait for Retry-After
run_queue_fullThe key already has 20 queued startsWait or cancel a request
idempotency_key_reusedSame Idempotency-Key, different bodyUse a new key for a new action
idempotency_in_progressThe first request with this key is still runningRetry shortly
invalid_idempotency_keyThe key value is not validUse a UUID
INSUFFICIENT_CREDITSThe workspace lacks creditsAdd credits
API_KEY_BUDGET_EXCEEDEDA daily, weekly or monthly cap is reachedWait for resetsAt or raise the cap
PLAN_NOT_ENTITLEDThe plan does not include the APIUpgrade to Creator or higher
api_disabledThe public API is switched offContact support
webhook_limit_reachedThe workspace has 10 webhook endpointsDelete one you no longer use
idempotency_response_unavailable409: the first request with this Idempotency-Key finished but its answer can no longer be replayedCheck the result with a GET, or use a new key
invalid_requestThe body or a parameter is not validFix the request using the error message
run_not_owned_by_api_key403: a key can retry or resume only runs it startedUse the key that started the run
webhook_test_rate_limitedTest deliveries are limited to 5 per minute, one pending at a timeWait for Retry-After
PLAN_NOT_ENTITLED (after a downgrade)402 on any request: the plan is re-checked on every requestUpgrade the plan
RUN_RATE_LIMITEDThe hourly run limit is full for a resume or retryWait for Retry-After; a start is queued instead, see Runs
run_request_not_cancellableThe run request is no longer queuedRead its status
CONTENT_MODERATION_PENDINGThe output is still being checked (202)Retry after Retry-After
CONTENT_BLOCKEDThe output was blocked by a content check (422)The output cannot be shared
webhook_disabledThe webhook endpoint is disabled (409)Set enabled to true

Run starts and run control calls (stop, resume, retry) also return the same codes and messages as the dashboard. Read error.message for the reason.