Errors and limits

Use this page after the normal workflow is clear. Error messages are designed to identify the next action without exposing resources from other teams.

Common HTTP statuses

Status	Meaning	Typical action
400	Invalid name, file, secret, webhook, or request value	Correct the request before retrying
401	Missing, invalid, expired, or locked authentication	Refresh or replace the credential
403	Credential type or role is not allowed	Use a user session or obtain the required team role
404	Resource not found in the selected team	Check the ID, name, version, and team
409	Active deployment already exists or cannot be deleted	Choose a version or wait for active work
422	Request shape does not match the endpoint schema	Correct JSON types and required fields
429	Rate limit, authentication lockout, or queue capacity reached	Back off before retrying

Deployment failures

deployment already exists

An active deployment already uses that name and version. Deploy a new version or delete the old deployment after all of its runs are terminal.

build_failed

Inspect the deployment’s build logs. Common causes are a misspelled requirement, incompatible pinned packages, or a setup command that exited non-zero.

Invalid deployment name

Use lowercase letters, digits, and single hyphens. Names must not be UUID-shaped or use reserved route words.

Run failures

Queue timeout

The run remained queued beyond the environment’s maximum queue age. Reduce burst concurrency or retry when capacity is available.

Execution timeout

The handler exceeded its per-run timeout. Reduce the work, split it into multiple invocations, or select a larger timeout through the SDK when appropriate.

Handler exception

Inspect the run error and its event timeline. Events emitted before the exception remain available.

Current limits

Resource	Limit or default
Handler runtime	Python 3.12
Default run timeout	300 seconds
Default handler retries	0
Deployment secrets	50
Secret value	8 KiB encoded
Handler events per invocation	1,000 plus one truncation marker
Event name or message	4,096 characters
Event structured data	16 KiB serialized
Stored build output	64 KiB
Default list page	50 items
Maximum list page	200 items

Environment operators can configure queue, concurrency, webhook, and some timeout limits. Do not build application correctness around an assumed queue delay.

Retry guidance

Retry 429 and transient server or network failures with exponential backoff and jitter. Do not blindly retry 400, 403, 404, 409, or 422; those require a request or workflow change.

Only enable run retries for idempotent handlers. If a handler charges a card, sends a message, or writes to an external system, use an idempotency key at that boundary.

Getting useful diagnostics

When asking for help, include:

• the handler name and run number, such as reviewer#42
• the selected deployment version
• the terminal status and redacted error
• relevant event names and timestamps

Never include API keys, secret values, authorization headers, or sensitive run input.