Skip to main content

Error Handling & Troubleshooting

The in-app reference lists every status code and error body: https://app.bike4mind.com/api/v1/docs. The raw spec is at https://app.bike4mind.com/api/v1/openapi.json. This page explains how errors behave.

Two places an error can appear​

Before the stream opens. The server validates the credential, scopes, rate limit, body, model and your credits before it calls the model provider. A failure here returns a JSON error body with a real HTTP status. No stream opens.

After the stream opens. The HTTP status is already 200 and stays 200. A failure arrives as one terminal error event in the stream:

{ "type": "error", "message": "...", "requestId": "...", "code": "provider_error" }

An error event is not followed by data: [DONE]. A stream that ends with neither is incomplete.

Branch on the HTTP status and errorCode (JSON), or on the event's code (stream). Never branch on error or message: they are prose and can change. code is optional, so keep a default branch that shows message and logs requestId.

Authentication and scopes​

  • 401 means the key is missing, malformed, revoked or expired. Create a new key from the Profile menu -> More -> API Keys. See Authentication.
  • Body validation runs before authentication, so a malformed body returns 422 (or 400 for an empty messages array) even without credentials.
  • 403 with required_scopes in the body means the API key does not hold any of the required scopes (ai:chat or ai:generate). Edit the key's scopes or create a new key.
  • 403 without required_scopes can mean the account is suspended or under a dispute; contact support. JWT requests can also require MFA enrollment: complete enrollment in the web app. Changing key scopes does not resolve these account restrictions.

Credits​

  • 422 with errorCode: "insufficient_credits" means you cannot afford the request: your personal balance, your organization's balance, or an organization per-member credit cap. Other 422 responses mean the body failed schema validation.
  • On an open stream, running out of credits mid-generation arrives as an error event with code: "insufficient_credits".
  • B4M never returns 402.

Top up before retrying; the same request fails again until the balance or cap changes.

Daily free-tier limit​

HTTP 429 with errorCode: "daily_free_limit_reached" means your personal spending has reached the free-tier daily allowance. Wait the Retry-After number of seconds before sending another request; the allowance resets at midnight UTC. A positive credit balance does not override this limit, and an immediate retry or a balance top-up alone does not reset it.

If you expected organization billing, check that the request or API key selects the intended organization. Organization-billed turns are exempt from this personal limit. The limits are deployment settings, so contact your deployment administrator if the allowance differs from the defaults.

Stream error codes​

codeMeaningRetry?
insufficient_creditsCredits ran out mid-generation.After a top-up
invalid_requestThe provider rejected your input.No, change the request
content_blockedThe model declined the request.No, rephrase or pick another model
provider_rejectedThe provider refused B4M's credentials. Your key is fine.Later, or another model
provider_errorAny other provider failure.Yes, with backoff

Account-level limits​

Your key has a per-minute and a daily request limit. Some accounts also have a tokens-per-minute limit and a limit on completions in flight at once. A 429 for one of these names it in errorCode:

  • api_key_rate_limit_exceeded: the key's per-minute request limit. Wait for Retry-After seconds.
  • api_key_daily_limit_exceeded: the key's daily request limit. Wait for Retry-After seconds.
  • token_rate_limit_exceeded: wait for Retry-After seconds. A retry can be refused again while your usage in the last minute is still over the limit.
  • concurrency_limit_exceeded: retry when one of your running completions finishes.

A 429 body for the request and token limits may also carry limit (the limit that was hit) and windowSeconds (its window). A concurrency refusal carries limit only.

Retry guidance​

StatusRetry?
400, 401, 403, 413, 422No. Fix the request, key, scopes or balance first.
404 with run_not_foundNo. Resend without run, or use a run you created. On GET /api/v1/completion-runs/{runId}/usage, read a run you created.
429Yes. Wait Retry-After seconds. See Account-level limits for the errorCode values.
500, 503Yes, with exponential backoff. A 503 with errorCode: "provider_not_configured" means the model's provider is unavailable here; try later or another model.

Log the request_id from the error body (also sent as the X-Request-ID header) and include it when you contact support.

Runs​

A 404 with errorCode: "run_not_found" means the run.runId in your request is not a run you created. It is returned before any credit hold or provider call, so nothing is charged. It is not retryable unchanged: resend without run, or mint a new run with POST /api/v1/completion-runs. See Streaming.

GET /api/v1/completion-runs/{runId}/usage returns the same 404 for a run you did not create, including one that does not exist. It is a read, so nothing is charged either way.

Unknown model​

A 400 with errorCode: "unknown_model" means the model id is not available to you. Check GET /api/v1/models for the ids you can use.

End user id not allowed​

A 400 with errorCode: "end_user_id_not_allowed" means the request sent end_user_id on an API key without the ai:end-user-id scope, or with a signed-in session. Remove the field, or ask your administrator to grant the scope to the key. See End users of your product.

Invalid end user id​

A 400 with errorCode: "invalid_end_user_id" means end_user_id was empty, longer than 64 characters, or contained anything other than letters, digits, _, : and - (an email address is never valid). This is checked before the credential, so it applies to every caller. See End users of your product.