---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/errors
markdown_url: https://steel.dev/docs/reference/errors.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Errors
description: Fix a failed Steel API request. Each error code has its HTTP status, its exact message and the fix.
summary: Fix a failed Steel API request.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/mcp-tools.md
  - https://steel.dev/docs/reference/commands.md
  - https://steel.dev/docs/reference/proxy-locations.md
  - https://steel.dev/docs/reference/signals.md
  - https://steel.dev/docs/reference/glossary.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Errors

When a request fails, the Steel API returns an HTTP status and a JSON body with an error code, a message and whether a retry can help. The Commands API returns its errors in its own shape, and some errors have no code.

## Error response

An error has a `4xx` or `5xx` status and a JSON body:

```json nocopy
{
  "error": "Conflict",
  "code": "profile_not_ready",
  "message": "Profile '45fd0b33-ed3e-4b4c-ac7c-55183a266677' is not ready yet. It is saved after the session that created it is released. If that session is still running, release it, then retry in 5 seconds.",
  "param": "profileId",
  "retryable": true,
  "retryAfterSeconds": 5,
  "linkToDocs": "https://docs.steel.dev/overview/sessions-api/reusing-auth-context"
}
```

| Field | Type | Description |
| - | - | - |
| `error` | string | The name of the HTTP status, such as `Bad Request`. |
| `code` | string | A stable reason for the error, such as `profile_not_ready`. Branch on it, not on the message. Some errors have no code. See [Errors without a code](https://steel.dev/docs/reference/errors#errors-without-a-code). |
| `message` | string | What went wrong and how to fix it, for a person or agent to read. Always present. The text can change. |
| `param` | string | The request field that caused the error, such as `useProxy` or `dimensions.width`. |
| `retryable` | boolean | Whether the same request can succeed later without changes. `false` means that you must fix the request or account first. |
| `retryAfterSeconds` | integer | The number of seconds to wait before a retry. |
| `linkToDocs` | string | A page of the docs that explains the fix. |

An error with `retryable` also has an `x-should-retry` header with the same value, `true` or `false`. An error with `retryAfterSeconds` also has the header `retry-after`.

A few endpoints send a shorter body, with only `message`, or with `error`, `message` and `linkToDocs`. The [Commands](https://steel.dev/docs/control/commands) endpoints use their own shape. See [Commands API errors](https://steel.dev/docs/reference/errors#commands-api-errors).

## Retry an error

Retry a request only when `retryable` is `true`. Wait `retryAfterSeconds` when the error has it. Otherwise, wait a short time that grows after each failure.

When an error does not set `retryable` itself, the API sets it from the status. Use the same rule for an error that has no `retryable` field:

| Status | `retryable` |
| - | - |
| `408`, `425`, `429` | `true` |
| `500` and every other `5xx` status except `501` | `true` |
| Every other status | `false` |

The [TypeScript](https://steel.dev/docs/reference/sdks/typescript), [Python](https://steel.dev/docs/reference/sdks/python), [Go](https://steel.dev/docs/reference/sdks/go) and [Rust](https://steel.dev/docs/reference/sdks/rust) SDKs read `x-should-retry` and retry for you.

## Error codes

| Code | Status | Retryable |
| - | - | - |
| [`invalid_request`](https://steel.dev/docs/reference/errors#invalid-request) | `400` | No |
| [`invalid_proxy_config`](https://steel.dev/docs/reference/errors#invalid-proxy-config) | `400` | No |
| [`invalid_proxy_url`](https://steel.dev/docs/reference/errors#invalid-proxy-url) | `400` | No |
| [`plan_feature_unavailable`](https://steel.dev/docs/reference/errors#plan-feature-unavailable) | `400` | No |
| [`session_timeout_exceeded`](https://steel.dev/docs/reference/errors#session-timeout-exceeded) | `400` | No |
| [`missing_api_key`](https://steel.dev/docs/reference/errors#missing-api-key) | `401` | No |
| [`invalid_api_key`](https://steel.dev/docs/reference/errors#invalid-api-key) | `401` | No |
| [`insufficient_funds`](https://steel.dev/docs/reference/errors#insufficient-funds) | `402` | No |
| [`budget_exceeded`](https://steel.dev/docs/reference/errors#budget-exceeded) | `402` | No |
| [`account_suspended`](https://steel.dev/docs/reference/errors#account-suspended) | `403` | No |
| [`deposit_required`](https://steel.dev/docs/reference/errors#deposit-required) | `403` | No |
| [`core_browser_locked`](https://steel.dev/docs/reference/errors#core-browser-locked) | `403` | No |
| [`profile_not_found`](https://steel.dev/docs/reference/errors#profile-not-found) | `404` | No |
| [`profile_not_ready`](https://steel.dev/docs/reference/errors#profile-not-ready) | `409` | Yes |
| [`profile_upload_failed`](https://steel.dev/docs/reference/errors#profile-upload-failed) | `422` | No |
| [`concurrency_limit_reached`](https://steel.dev/docs/reference/errors#concurrency-limit-reached) | `429` | Yes |
| [`rate_limited`](https://steel.dev/docs/reference/errors#rate-limited) | `429` | Yes |

In the messages below, a word in capitals, such as `FIELD` or `PLAN`, stands for a value that the API fills in. `PLAN` is the internal name of your plan, which can differ from the names on [Pricing](https://steel.dev/docs/platform/pricing).

### invalid_request

Status `400`. The request does not match the endpoint's schema. `param` names the field, and the message is one of these:

```text nocopy
Request validation failed. Check the request fields and retry.
FIELD is invalid. Check the value and retry.
'FIELD' is required. Add 'FIELD' to the request and retry.
FIELD must be of type `TYPE`. Fix the value and retry.
FIELD is not one of the supported values. Use one of the documented values and retry.
FIELD must be a valid URL including the scheme, e.g. https://example.com.
FIELD must be a valid UUID. Copy the id returned by Steel and retry.
FIELD must contain a non-whitespace character.
sessionId must be a valid UUID, e.g. 123e4567-e89b-12d3-a456-426614174000. Omit it to let Steel generate one for you.
profileId must be a valid UUID. Copy the id from the profile you created, or omit profileId if you do not want to attach a profile.
```

**Fix:** Correct the field in `param`. Each endpoint's page under [API reference](https://steel.dev/docs/reference/api) lists its fields, and [Session configuration](https://steel.dev/docs/sessions/configuration) lists the fields of a new session.

### invalid_proxy_config

Status `400`. `param` is `useProxy`.

```text nocopy
'useProxy' must be true, false, { geolocation: { country: 'US' } }, { server: 'http://user:pass@host:port' }, or { type: 'fixed', id?: 'fixed:<id>' }. Fix 'useProxy' and retry.
```

**Fix:** Pass `useProxy` in one of the forms in [useProxy](https://steel.dev/docs/sessions/configuration#useproxy).

### invalid_proxy_url

Status `400`. `param` is `proxyUrl` or `useProxy.server`, and `PARAM` in the message is the same field.

```text nocopy
'PARAM' must be a valid http:// or https:// URL, e.g. http://user:pass@host:port.
'PARAM' must use http:// or https://, not SCHEME//. Use an HTTP(S) proxy, e.g. http://user:pass@host:port.
```

**Fix:** Pass the URL of an HTTP or HTTPS proxy, with the username and password in it. See [Proxies](https://steel.dev/docs/stealth/proxies).

### plan_feature_unavailable

Status `400`. Only organizations on the legacy Hobby plan get this error. The request uses a Steel proxy or CAPTCHA solving, which Hobby does not include. `param` is `useProxy`, `solveCaptcha` or `profileId`. On Launch, the same request gets [`deposit_required`](https://steel.dev/docs/reference/errors#deposit-required).

```text nocopy
Steel proxies are not available on the hobby plan. Either pass your own proxy via 'proxyUrl', remove 'useProxy', or upgrade your plan to use Steel proxies.
Captcha solving is not available on the hobby plan. Remove 'solveCaptcha' from the request, or upgrade your plan to enable it.
This request routes through a Steel proxy (via the resolved profile's saved proxy config), which is not available on the hobby plan. Use a profile without a Steel proxy, pass your own 'proxyUrl', or upgrade your plan.
```

**Fix:** Remove the option, use your own proxy in `proxyUrl`, or move to a current plan. [Pricing](https://steel.dev/docs/platform/pricing) lists what each plan includes.

### session_timeout_exceeded

Status `400`. `param` is `timeout`. The requested `timeout` is longer than your plan allows.

```text nocopy
Requested 'timeout' of REQUESTED ms exceeds the maximum of LIMIT on the PLAN plan. Set 'timeout' to MAXIMUM or less, or upgrade your plan for longer sessions.
```

**Fix:** Set `timeout` to the maximum in the message or less. [Limits](https://steel.dev/docs/platform/limits) lists the maximum session length of each plan. This error is not the [signal](https://steel.dev/docs/reference/signals) of the same name.

### missing_api_key

Status `401`. The request has no API key.

```text nocopy
Missing API key. Send your Steel API key in the 'steel-api-key' header. Create or rotate a key at https://app.steel.dev/settings/api-keys.
```

**Fix:** Send the key in the `steel-api-key` header. See [Authentication](https://steel.dev/docs/reference/api#authentication).

### invalid_api_key

Status `401`. The key does not match any account.

```text nocopy
Invalid Steel API key. The key sent in the 'steel-api-key' header does not match any account. Create or rotate a key at https://app.steel.dev/settings/api-keys.
Invalid Steel API key. Provide a valid key via the 'steel-api-key' header. Create or rotate one at https://app.steel.dev/settings/api-keys.
```

**Fix:** Check the key for typing errors and extra spaces, and make sure that your code reads the right environment variable. A deleted key stops working at once. See [API keys](https://steel.dev/docs/account/api-keys).

### insufficient_funds

Status `402`. Your account has no credits, so Steel refuses new sessions. Sessions that are already running are not affected.

```text nocopy
Your account is out of credits, so new sessions are refused. Add funds at https://app.steel.dev/settings/billing, then retry.
```

**Fix:** Add credits in [Billing and usage](https://steel.dev/docs/platform/billing-and-usage), then send the request again.

### budget_exceeded

Status `402`. Your account reached its monthly spending limit.

```text nocopy
Your account reached its monthly spending limit, so new sessions are refused until it resets at the start of next month (UTC). Raise or remove the limit at https://app.steel.dev/settings/billing/limits to resume sooner, then retry.
```

**Fix:** Raise or remove the spending limit in [Billing and usage](https://steel.dev/docs/platform/billing-and-usage), or wait until the first day of the next month (UTC).

### account_suspended

Status `403`. Steel suspended your organization. The API returns this error for every request, and a CDP connection gets it too.

```text nocopy
Your Steel account is suspended, so this request was rejected. Email support@steel.dev to resolve it and restore access.
```

**Fix:** Contact [Support](https://steel.dev/docs/support).

### deposit_required

Status `403`. On Launch, CAPTCHA solving and Steel proxies need a verified account, and the organization has not verified its account. You verify it once: when your paid credits reach $10, the features stay on, even after you spend the credits. The message says "at least $10 in paid balance", but the balance does not have to stay at $10. [Verify a Launch account](https://steel.dev/docs/platform/pricing#verify-a-launch-account) explains how to verify. `param` is `solveCaptcha` when the request asks for CAPTCHA solving. The message names the features that the request uses. The last message below is for a [Quick action](https://steel.dev/docs/control/scrape#deposit-required), which takes no `proxyUrl`:

```text nocopy
This request uses CAPTCHA solving ('solveCaptcha'). On the Launch plan, CAPTCHA solving and Steel proxies need at least $10 in paid balance. Add credits at https://app.steel.dev/settings/billing, remove 'solveCaptcha', or upgrade to Scale.
This request uses a Steel proxy. On the Launch plan, CAPTCHA solving and Steel proxies need at least $10 in paid balance. Add credits at https://app.steel.dev/settings/billing, pass your own 'proxyUrl' instead of a Steel proxy, or upgrade to Scale.
This request uses a Steel proxy. On the Launch plan, CAPTCHA solving and Steel proxies need at least $10 in paid balance. Add credits at https://app.steel.dev/settings/billing, set 'useProxy' to false, or upgrade to Scale.
```

**Fix:** Verify your account, remove the feature from the request, or change your plan in [Billing and usage](https://steel.dev/docs/platform/billing-and-usage).

### core_browser_locked

Status `403`. `param` is `experimentalFeatures`. The request turns on Stealth Browser. Your organization has early access to it, but its plan does not include it, and it has no trial. The message calls Stealth Browser Core Browser.

```text nocopy
Core Browser ('useStealthBrowser' in 'experimentalFeatures') is not available on your plan. Remove it from 'experimentalFeatures', or upgrade your plan.
```

**Fix:** Remove `useStealthBrowser` from `experimentalFeatures`, or ask Steel to add Stealth Browser to your plan. An organization with no access at all, neither early access nor a plan or trial that includes it, gets a `403` without a code instead. See [Stealth Browser](https://steel.dev/docs/stealth/stealth-browser#troubleshooting).

### profile_not_found

Status `404`. `param` is `profileId`.

```text nocopy
Profile 'PROFILE_ID' not found. It may have expired (profiles have a TTL) or belong to a different organization. Check the id, or create a new profile.
```

**Fix:** Check the profile's ID and project. If the profile expired, create a new one. See [Profiles](https://steel.dev/docs/logins/profiles).

### profile_not_ready

Status `409`. `param` is `profileId`. Steel saves a profile after the session that created it is released, and this profile is not saved yet. The error is retryable, and `retryAfterSeconds` is `5`.

```text nocopy
Profile 'PROFILE_ID' is not ready yet. It is saved after session 'SESSION_ID' is released. If that session is still running, release it (POST /v1/sessions/SESSION_ID/release), then retry in 5 seconds.
```

**Fix:** Release the session that created the profile. Wait `retryAfterSeconds`, then send the request again.

### profile_upload_failed

Status `422`. `param` is `profileId`. Steel could not save the profile, and the profile cannot be used.

```text nocopy
Profile 'PROFILE_ID' failed to upload and cannot be used. Create a new profile and reference that one instead.
```

**Fix:** Create a new profile and pass its ID. See [Profiles](https://steel.dev/docs/logins/profiles).

### concurrency_limit_reached

Status `429`. Your organization runs as many sessions as its plan allows. A [Quick action](https://steel.dev/docs/reference/api/quick-actions) also counts, because it runs a short session.

```text nocopy
Concurrent session limit reached for your PLAN plan (CURRENT of LIMIT sessions running). Release a running session (POST /v1/sessions/{id}/release) before creating another, or upgrade your plan for a higher limit.
Concurrent session limit reached for your PLAN plan. This endpoint creates a short-lived session. Wait for a running session to finish or release one, or upgrade your plan for a higher limit.
Concurrent session limit reached. Release a running session before creating another, or upgrade your plan for a higher limit.
```

When the plan is unknown, the message says `your current plan`.

**Fix:** Release a session that you no longer need, then send the request again. To run more sessions at once, see [Know your limits](https://steel.dev/docs/production/run-sessions-at-scale#know-your-limits) and [Limits](https://steel.dev/docs/platform/limits).

### rate_limited

Status `429`. You went over a rate limit: the number of sessions that your plan lets you create per minute, or the rate limit of a Quick action. The error has `retryAfterSeconds` and the `retry-after` header.

```text nocopy
Session create rate limit reached: your plan allows LIMIT session creates per minute. Retry in SECONDS seconds.
Rate limit exceeded. Your plan only allows LIMIT requests per WINDOW. Try again in SECONDS seconds.
```

**Fix:** Wait `retryAfterSeconds`, then send the request again. [Limits](https://steel.dev/docs/platform/limits) lists the rates of each plan.

## Commands API errors

The [Commands](https://steel.dev/docs/control/commands) endpoints, `POST /v1/sessions/SESSION_ID/commands` and the execution endpoints, return errors in another shape. The body has a code and a message:

```json nocopy
{
  "error": {
    "code": "session_ended",
    "message": "Session 1a515295-14d0-4039-9bca-06ee68e74018 has ended. Create a new session to keep going."
  }
}
```

These errors have no `retryable` field. Read the `x-should-retry` header where the table says so, and wait for `retry-after` when it is set. A `401` or `403` from these endpoints has the shape in [Error response](https://steel.dev/docs/reference/errors#error-response).

| Code | Status | Message | What to do |
| - | - | - | - |
| `invalid_request` | `400` | The problem in the body, such as `The body is not valid JSON: DETAIL` or `Idempotency-Key must be 1 to 255 characters.` | Fix the body. No command ran. |
| `session_not_found` | `404` | `Session SESSION_ID was not found. Check the session id, or create a new session.` | Check the session ID. |
| `session_ended` | `410` | `Session SESSION_ID has ended. Create a new session to keep going.` | Create a new session. |
| `key_conflict` | `422` | `This Idempotency-Key was already used with different commands.` | Use a new `Idempotency-Key` for different commands. |
| `invalid_operation_token` | `422` | `Operation AFTER is unknown or expired. If you sent these commands before, check the page first, because they may have run. Then send again with the next value from this response.` | Check the page, then send again with the `next` value of the response. |
| `unknown_execution` | `422` | `Execution EXECUTION_ID is not known in this session.` | Check the execution ID. |
| `missing_capability` | `422` | `The browser of session SESSION_ID does not support commands. Create a new session.` | Create a new session. |
| `queue_full` | `429` | `Too many executions are waiting in this session.` | Wait for `retry-after`, then send again. |
| `records_full` | `429` | `This session holds too many execution records.` | Wait for `retry-after`, then send again. |
| `expired` | `429` | `The execution could not start before the response deadline. Send the same request again.` | Send the same request again. |
| `internal_error` | `500` | The message of the unexpected error. | Send again only if `x-should-retry` is `true`. |
| `delivery_failed` | `503` | `Could not reach the browser of session SESSION_ID. The commands did not run, so it is safe to send them again.` | Send again if `x-should-retry` is `true`. |

`delivery_failed` has a second message, for the case where the commands may have run:

```text nocopy
Could not reach the browser of session SESSION_ID, so the commands may or may not have run. Retry with the same Idempotency-Key or after to get the stored result instead of running them twice.
```

In that case, `x-should-retry` is `true` only when the request had an `Idempotency-Key` or an `after` value. See [Idempotency](https://steel.dev/docs/reference/api#idempotency).

### Command result errors

A command that fails inside a run does not fail the request. The response has status `200`, and the command's result has an `error` with a `code`, a `message` and sometimes a `reason`. The commands after it do not run.

| Code | Meaning |
| - | - |
| `stale_ref` | The ref's element left the page or now shows other content. Take a new snapshot. |
| `not_actionable` | The element cannot take the input, for example because it is covered or disabled. |
| `dialog_pending` | A JavaScript dialog blocks the tab. Send `press` with `Enter` to accept it or `Escape` to dismiss it. See [Dialogs](https://steel.dev/docs/reference/commands#dialogs). |
| `element_not_found` | No element matches the target. |
| `invalid_argument` | A field has a bad value, or a locator matches more than one element. |
| `tab_not_found` | The tab does not exist. |
| `tab_crashed` | The tab crashed. |
| `frame_not_found` | The frame does not exist or is not an iframe. |
| `tab_required` | More than one tab is open, so the command must name one. |
| `forbidden_url` | The URL is not allowed. |
| `forbidden_file` | The file is not allowed. |
| `navigation_failed` | The page did not load. |
| `download_failed` | The download did not complete. |
| `script_error` | The `eval` script threw an error. |
| `timeout` | The command ran out of time. |
| `cancelled` | The command was cancelled. |
| `session_ended` | The session ended. |
| `browser_restarted` | The browser started again. |
| `unknown_command` | The command does not exist or cannot run here. |
| `internal_error` | Steel hit an unexpected error. |

`reason` adds detail, such as `covered`, `offscreen`, `no_box`, `disabled`, `read_only`, `not_editable`, `ambiguous`, `detached`, `content_changed`, `missing`, `not_frame`, `dialog_closed` or `unanswered`. [Commands reference](https://steel.dev/docs/reference/commands) lists the commands.

## Errors without a code

Some errors have no `code`. Use the status and message.

| Status | Meaning | What to do |
| - | - | - |
| `400` | The request is not valid. | Read the message and fix the request. |
| `401` | The credentials are not valid. | Check the API key. See [Authentication](https://steel.dev/docs/reference/api#authentication). |
| `403` | The request is not allowed for your organization or project. | Check the resource's project and your plan's features. |
| `404` | The resource does not exist, or it belongs to another organization or project. A session that ended can also return `404`. | Check the ID and project. |
| `409` | The request conflicts with the resource's state. | Read the message. |
| `410` | The resource is gone. | Create a new resource. |
| `413` | The request body is too large. | Send a smaller file. See [Limits](https://steel.dev/docs/platform/limits). |
| `415` | The request's content type is not supported. | Send the content type that the endpoint takes. See [Content types](https://steel.dev/docs/reference/api#content-types). |
| `422` | The request is valid, but Steel cannot process it. | Read the message. |
| `500` | Steel hit an unexpected error. | Retry with a growing wait. If it repeats, contact [Support](https://steel.dev/docs/support). |
| `502` | A service behind the API failed. A Quick action that could not store its file also returns `502`, as [Troubleshooting](https://steel.dev/docs/control/scrape#steel-ran-the-action-but-could-not-store-its-result-file) on the Scrape page explains. | Retry with a growing wait. |
| `503` | Steel has no capacity now, or a service is down. | Retry with a growing wait. |
| `504` | A step took too long. For a new session, the browser did not become ready in time. No session runs. Steel can still list the attempt as a session with the status `failed`. | Retry with a growing wait. |

These are the messages of the most common errors without a code:

```text nocopy
Session not found. It may have ended, expired, or belong to a different organization. Check the session id, or list your sessions to confirm it exists.
Steel hit an unexpected server error while processing this request. Retry shortly; if it persists, contact support with the request details.
No browser capacity is currently available. This is usually transient — retry shortly.
Steel could not start a browser session. No session was created — retry shortly; if it repeats, try a simpler session configuration.
The browser session did not become ready in time. No session was created — retry shortly; if you passed 'proxyUrl', 'profileId', or extensions, try again with a simpler session configuration.
```
