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:
{
"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. |
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.. |
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 endpoints use their own shape. See 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, Python, Go and Rust SDKs read x-should-retry and retry for you.
Error codes
| Code | Status | Retryable |
|---|---|---|
invalid_request | 400 | No |
invalid_proxy_config | 400 | No |
invalid_proxy_url | 400 | No |
plan_feature_unavailable | 400 | No |
session_timeout_exceeded | 400 | No |
missing_api_key | 401 | No |
invalid_api_key | 401 | No |
insufficient_funds | 402 | No |
budget_exceeded | 402 | No |
account_suspended | 403 | No |
deposit_required | 403 | No |
core_browser_locked | 403 | No |
profile_not_found | 404 | No |
profile_not_ready | 409 | Yes |
profile_upload_failed | 422 | No |
concurrency_limit_reached | 429 | Yes |
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.
invalid_request
Status 400. The request does not match the endpoint's schema. param names the field, and the message is one of these:
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 lists its fields, and Session configuration lists the fields of a new session.
invalid_proxy_config
Status 400. param is useProxy.
'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.
invalid_proxy_url
Status 400. param is proxyUrl or useProxy.server, and PARAM in the message is the same field.
'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.
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.
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 lists what each plan includes.
session_timeout_exceeded
Status 400. param is timeout. The requested timeout is longer than your plan allows.
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 lists the maximum session length of each plan. This error is not the signal of the same name.
missing_api_key
Status 401. The request has no API key.
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.
invalid_api_key
Status 401. The key does not match any account.
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.
insufficient_funds
Status 402. Your account has no credits, so Steel refuses new sessions. Sessions that are already running are not affected.
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, then send the request again.
budget_exceeded
Status 402. Your account reached its monthly spending limit.
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, 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.
Your Steel account is suspended, so this request was rejected. Email support@steel.dev to resolve it and restore access.Fix: Contact 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 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, which takes no proxyUrl:
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.
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.
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.
profile_not_found
Status 404. param is profileId.
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.
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.
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.
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.
concurrency_limit_reached
Status 429. Your organization runs as many sessions as its plan allows. A Quick action also counts, because it runs a short session.
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 and 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.
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 lists the rates of each plan.
Commands API errors
The 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:
{
"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.
| 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:
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.
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. |
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 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. |
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. |
415 | The request's content type is not supported. | Send the content type that the endpoint takes. See 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. |
502 | A service behind the API failed. A Quick action that could not store its file also returns 502, as Troubleshooting 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:
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.