Errors - Labelbox

Every failed request returns the same JSON shape with a stable code. Branch on code, never on message. This page lists every code you can receive, what causes it, and whether to retry.

The error shape

{
  "code": "idempotency_in_progress",
  "message": "a request with this Idempotency-Key is already in progress",
  "details": {
    "field": "Idempotency-Key",
    "requestId": "0b6f2c1d-9a4e-4b7f-8c3d-5e6a7b8c9d0e"
  }
}

Field	Use
`code`	Stable and machine-readable. Branch on this.
`message`	For people. It can change at any time.
`details`	Code-specific context, such as `field`, measured values, limits, or the next call to make.
`details.retryable`	`true` when the same request can succeed later. Some `429` and `503` responses omit it; retry those with backoff anyway.
`details.requestId`	Include this, and the `x-request-id` response header, when you report a problem.

How to retry

Situation	What to do
`Retry-After` header present	Wait that long, then retry. It’s sent with some `409`, `429`, `503`, and `504` responses.
`details.retryable: true`, no `Retry-After`	Retry with exponential backoff and jitter, starting around one second.
`5xx` on a create	Retry with the same `Idempotency-Key`, so the create can’t happen twice.
Any other `4xx`	Don’t retry unchanged. Fix the request first.

Request and validation

Status and code	Cause	Fix	Retry?
`400 invalid_request`	A field, query parameter, or header is missing, malformed, or out of range. `details.field` names it. Also returned when the body isn’t valid JSON, a tenant-scoped key omits `x-organization-id`, `Idempotency-Key` is malformed or repeated, or a `page_token` has expired or doesn’t match the query. Session-list tokens last one hour.	Fix the named field. For a `page_token`, restart the list without it.	No
`400 invalid_json`	The body is JSON but doesn’t match the operation’s schema, such as a field with the wrong type. `details.field` names the field when it’s known.	Check the body against Endpoints.	No
`413 payload_too_large`	The body is bigger than the operation accepts, for example a skill bundle over 8 MiB.	Send a smaller body.	No
`415 unsupported_media_type`	The body’s media type isn’t accepted. Skill bundles are the only `multipart/form-data` upload.	Send JSON with `Content-Type: application/json`.	No

Authentication and access

Status and code	Cause	Fix	Retry?
`401 unauthorized`	No API key, or the key is malformed, expired, revoked, or no longer active.	Check the `Authorization: Bearer` header. See API keys.	No
`403 forbidden`	The key is valid, but your role in the organization doesn’t allow this operation.	See Organizations and roles. Use an account or key with the developer or admin role.	No
`404 not_found`	The resource doesn’t exist, or it’s in an organization you can’t reach. Also returned for an `x-organization-id` you can’t use, and for any path the API doesn’t serve. The cases look the same on purpose.	Check the id, the path, and the organization.	No
`503 service_unavailable`	Your key couldn’t be checked right now. The request did not run.	Retry shortly.	Yes

Conflicts and concurrency

Status and code	Cause	Fix	Retry?
`409 conflict`	The request conflicts with the resource’s current state, such as a duplicate name, or deleting a session while its hard stop is still finishing.	Read the resource, then change the request.	Only when `details.retryable` is `true`.
`409 revision_conflict`	Someone published a newer agent or skill version after you read it, or an environment’s settings changed while your update was saving.	Read it again, apply your change to the latest version, and retry.	After re-reading
`409 vault_creation_retired`	The vault an earlier attempt created with this `idempotency_key` was deleted.	Create the vault again with a new `idempotency_key`.	No
`412 precondition_failed`	An environment update sent `expected_access` that no longer matches its network policy or privileged access.	Read the environment and retry with its current access settings.	After re-reading
`428 precondition_required`	An update changes an environment’s stored network policy, or turns on privileged access, without `expected_access`.	Read the environment and send its current access settings as `expected_access`.	After re-reading
`412 precondition_failed` on `If-Match`	An automation or event source changed after you read it.	Read it again and retry with its new ETag.	After re-reading
`428 precondition_required` on `If-Match`	A replace, pause, resume, or delete of an automation or event source sent no `If-Match`.	Send `If-Match: "revision-N"` from the last read.	After fixing
`409 content_sha256_mismatch`	A memory changed after you read it.	Read it again, reapply your change, and send the new `content_sha256`.	After re-reading

Idempotency

Status and code	Cause	Fix	Retry?
`409 idempotency_conflict`	The `Idempotency-Key` was already used for a different request.	Use a new key for a new request. Resend the exact same bytes to replay.	No
`409 idempotency_in_progress`	The first request with this key is still running.	Wait for `Retry-After`, then send the same request again.	Yes
`503 idempotency_unavailable`	The key couldn’t be checked or reserved. The request did not run.	Retry with the same key.	Yes

See Idempotent creates.

Rate limits and capacity

Status and code	Cause	Fix	Retry?
`429 rate_limit_exceeded`	You sent too many requests. The limit is per person, across all your keys.	Wait for `Retry-After`.	Yes
`429 rate_limited`	Your organization’s request rate limit is exhausted.	Wait for `Retry-After`.	Yes
`429 setup_run_limit`	Your organization has as many setup runs in flight as it may. `details.limit` is the cap and `details.in_flight` lists the runs.	Wait for a run to finish, or cancel one.	Yes
`503 service_unavailable`	The service is briefly unavailable, or at event-stream capacity.	Retry with backoff. For streams, close ones you no longer need.	Yes

Environments and setup

Status and code	Cause	Fix	Retry?
`422 environment_not_verified`	The environment’s setup script has never passed, failed, changed since it passed, or is still being tested. `details.next_action` names the call to make.	Run a setup test and wait for it to pass. See Environments.	Yes, while a test is running
`422 sandbox_provider_disabled`	The request names a runtime this deployment doesn’t offer for new work.	Use the Agent runner runtime (`runs`).	No
`422 setup_fallback_environment_unsafe`	The environment needs a fresh setup test before sessions can start, and one of its environment variables could run workspace code first.	Run a new setup test, or remove the flagged variable.	No
`409 setup_run_in_progress`	A setup run is already in flight for this environment. `details.setup_run_id` names it.	Wait for it, or cancel it.	After it ends
`409 setup_run_finished`	You tried to cancel a setup run that had already finished. Nothing changed.	None needed.	No
`503 setup_run_not_started`	The setup run was recorded but couldn’t start. It’s marked failed.	Start another setup run.	Yes

Integrations

Status and code	Cause	Fix	Retry?
`400 invalid_request` on `resources` or `permission`	A tool allow-list is empty, has more than 200 tools, names a tool the app doesn’t have, or holds a tool that isn’t read-only under the `read` preset.	Send 1 to 200 tool names from the catalog, or use `permission: "write"`. See Integrations.	No
`400 invalid_request` on `built_in_integrations`	An agent names more than 25 apps, sends `tools`, or names a connection that isn’t an active built-in integration with at least one tool.	Fix the entry `message` describes. See Grant apps to an agent.	No
`422 provider_selection_unsupported`	A tool allow-list change was sent for a native integration, whose access is set per agent.	Set the access on the agent instead.	No
`503 built_in_catalog_unavailable`	The app catalog couldn’t be loaded.	Retry.	Yes
`503 built_in_integrations_unconfigured`	The app catalog couldn’t be reached for your organization.	Contact support.	No
`503 integrations_unconfigured`	The integration service couldn’t be reached.	Retry later. If it persists, contact support.	Yes
`429 github_rate_limited`	GitHub is limiting requests made for your connection.	Retry after `Retry-After`.	Yes
`503 github_unavailable`	GitHub couldn’t be reached.	Retry later.	Yes

A connection check that fails still returns 200, with ok: false and a failure reason. See Check a connection.

Files

Status and code	Cause	Fix	Retry?
`413 file_quota_exceeded`	The upload would take your organization’s live files past its storage quota. `details` has `quota_bytes`, `used_bytes`, and `incoming_bytes`.	Delete files you no longer need, or set expiries.	After fixing
`404 not_found` on `file_id`	The file doesn’t exist in your organization, was deleted, or expired.	Use a live file id.	No
`409 conflict` on `resources`	An attachment path collides with another, or the session isn’t the root of its tree.	Choose another `relative_path`, or attach to the root.	After fixing

See Files.

Automations and event sources

Status and code	Cause	Fix	Retry?
`422 automation_reference_invalid`	The automation’s agent version or environment doesn’t exist or can’t be used.	Choose a live agent version and a verified environment.	After fixing
`422 automation_event_source_invalid`	A trigger names a missing or incompatible event source.	Use a source of the trigger’s type.	After fixing
`422 event_source_verification_credential_invalid`	The verification credential isn’t a live `webhook_secret` in your organization.	Store the secret as a Webhook signing secret.	After fixing
`409 conflict` on `eventSourceId`	The source is still used by automations, or it’s managed by its connection.	Remove it from triggers first, or manage it through its connection.	After fixing
`503 automation_memory_unavailable`	A run couldn’t attach a selected memory store with its access and instructions.	Retry the run.	Yes
`503 event_admission_unavailable`	A webhook delivery couldn’t be recorded. Returned to the sender.	The sender retries.	Yes

A run that can’t start its session ends failed with an error that has its own code, message, and retryable. See Automations.

Memory, evaluations, and analytics

Status and code	Cause	Fix	Retry?
`400 invalid_request` on `memory_store_id`	A write to an agent’s learned memory or an archived store.	Write to an active curated store.	No
`404 not_found` on `evaluation`	A selected session isn’t visible to you or can’t be evaluated.	Select root sessions with an agent from your organization.	After fixing
`409 evaluation_cancellation_pending` or `409 evaluation_deletion_pending`	An evaluation run is still cleaning up.	Retry after it finishes.	Yes
`400 invalid_scope`	An analytics family was read at a scope it doesn’t support.	Leave `scope` out.	No
`503 analytics_not_ready`	Analytics figures haven’t caught up yet.	Retry shortly.	Yes

Models and the session analyst

Status and code	Cause	Fix	Retry?
`503 model_gateway_unreachable`	The model list, or the model a request names, couldn’t be checked right now.	Retry later.	Yes
`503 session_analyst_busy`	Another request to the same session analyst was still running.	Retry.	Yes
`503 session_analyst_model_unavailable`	The session analyst’s model isn’t available.	Retry later.	Yes
`503 session_analyst_unconfigured`	The session analyst couldn’t be started for your organization.	Contact support.	No

Server errors

Status and code	Cause	Fix	Retry?
`500 internal_error`	An unexpected failure. Details are withheld.	Retry once with the same `Idempotency-Key` if it was a create. If it persists, report `details.requestId`.	Once
`500 invariant_violation`	An internal consistency check failed. Details are withheld.	Retry once. If it persists, report `details.requestId`.	Once
`502 bad_gateway`	An internal service returned an invalid response.	Retry with backoff.	Yes
`503 managed_agents_unavailable`	Managed Agents is temporarily unavailable.	Retry with backoff.	Yes
`504 gateway_timeout`	The request took too long. It may or may not have run.	Retry creates with the same `Idempotency-Key`. Read the resource before retrying other writes.	Yes
Any other `503` code	A service dependency is temporarily unavailable.	Retry with backoff. If it persists, report `details.requestId`.	Yes

Session failure codes

A session that fails has a failure object. These codes are separate from HTTP errors: the request that started the session succeeded, but the work later stopped.

{
  "status": "failed",
  "failure": {
    "code": "sandbox_provision_timeout",
    "phase": "provisioning",
    "category": "transient",
    "retryable": true,
    "message": "Agent runner provisioning timed out. The session may succeed when capacity recovers."
  }
}

Read category first:

`category`	Meaning	What to do
`transient`	A temporary condition.	Send a follow-up message to resume, or start again later.
`caller_error`	Something in your request or configuration. Retrying as is won’t help.	Fix the agent, environment, or grant, then resume or start a new session.
`internal`	A problem on our side.	Report the `session_id`.

`failure.code`	Cause	Fix
`sandbox_provision_timeout`	Compute wasn’t ready within 5 minutes.	Resume or start again.
`sandbox_capacity_unavailable`	Compute capacity was temporarily unavailable.	It’s retried automatically. If it persists, try again later.
`sandbox_image_pull_failed`	The image saved by the environment’s last passing setup test couldn’t be loaded.	None. It’s retried automatically without rerunning setup.
`sandbox_configuration_invalid`	The environment’s settings can’t be run.	Fix the environment. `message` says what’s wrong.
`sandbox_provider_unavailable`	The runtime was briefly unavailable.	Resume or start again.
`sandbox_gpu_not_ready`	The GPU didn’t pass its readiness check.	Report it. Starting again usually reproduces it.
`environment_setup_failed`	The setup script failed on the session’s compute.	Fix the script and test it again. See Environments.
`credential_resolution_failed`	A granted credential couldn’t be opened.	Check the session’s vault grants and that the credentials still exist.
`model_not_found`	The agent’s model isn’t available.	Update the agent to a model from `listModels`.
`model_rate_limited`	The model provider throttled the requests.	Resume later.
`model_provider_unavailable`	The model provider was unavailable.	Resume later.
`model_request_failed`	The model provider rejected a request.	Check the agent’s model settings, such as reasoning effort.
`model_reasoning_capacity_invalid`	The reasoning effort doesn’t fit the model’s output capacity.	Lower the agent’s reasoning effort or choose another model.
`model_refused`	The model declined to continue the task.	Change the task or instructions. Resuming repeats the refusal.
`roster_agent_unresolved`	A subagent in the roster names an agent, version, or model that doesn’t exist.	Fix the roster. See Multi-agent.
`worker_replaced`	A service update interrupted the work.	Send a follow-up message to resume if the session is still stopped.
`repository_provider_unavailable`	The repository host was unavailable.	Resume later.
`internal_error`	An unexpected failure.	Report the `session_id`.

Setup runs report the same failure vocabulary in their failure_code.

Next steps

Troubleshooting

Match a symptom to its cause and fix.

Limits

See the limit behind each size or rate error.

API conventions

Retries, idempotency, and paging.

Event types and states

Look up session statuses and stop reasons.

​The error shape

​How to retry

​Request and validation

​Authentication and access

​Conflicts and concurrency

​Idempotency

​Rate limits and capacity

​Environments and setup

​Integrations

​Files

​Automations and event sources

​Memory, evaluations, and analytics

​Models and the session analyst

​Server errors

​Session failure codes

​Next steps