Reference · Errors
Errors, in plain language.
Every dropthis API error is an RFC 7807 application/problem+json
document. Branch on code, stop retrying when
retryable is false, and show
suggestion to the user. The full, machine-readable
contract — including the conditional fields — lives in the
OpenAPI spec.
The Problem shape
- type
- A stable URI for the error type — a link to this page for the code.
- title
- Short, human summary of the error type.
- status
- The HTTP status code.
- detail
- Human-readable explanation specific to this one occurrence.
- code
- The stable machine code your SDK/agent branches on (the table below).
- retryable
- Whether retrying the identical request can succeed. Stop retrying when false.
- suggestion
- An actionable next step — the CLI/SDK/MCP show it verbatim.
- request_id
- Correlation id for this request; quote it in support reports.
Authentication
authentication_required 401 not retryable No credential, or it was missing. Send Authorization: Bearer <sk_… or at_…>.
invalid_api_key 401 not retryable The API key is unknown or revoked. Mint a new one in the console or via POST /v1/api-keys.
invalid_session 401 not retryable The session/token expired. Log in again to get a fresh credential.
otp_expired 401 retryable No active login code — request a fresh OTP and try again. (Safe to auto-resend.)
otp_invalid 401 not retryable Wrong login code. Re-check the digits; do not auto-resend (that emails on every typo).
rate_limit_exceeded 429 retryable Too many attempts. Wait for the retry window, then try again.
step_up_required 403 not retryable An irreversible action needs a fresh re-authentication (step-up) first.
Permissions (capability scopes)
insufficient_scope 403 not retryable The credential lacks the scope for this operation — e.g. a publish-only key tried a team op. Re-login or mint a key with the needed bundle: --scope team (CLI) or apiKeys.create({ scopes: ['team'] }) (SDK).
service_cannot_mint_delegated 403 not retryable A workspace-pinned service key can't mint an account-scoped key. Use a delegated key or a session.
Plans & quotas
feature_not_in_plan 403 not retryable The feature isn't on your plan (e.g. password protection, custom domain). The body carries required_plan and upgrade_url.
quota_exceeded 403 / 413 not retryable A limit was hit — per-drop or account storage (413) or team seats (403). Free up space/seats or upgrade; the body carries limit, used, requested.
Validation & conflicts
validation_error 422 not retryable A request field was invalid — the body's param names it.
not_found 404 not retryable The resource doesn't exist or isn't visible to your credential. For a drop, the id may be stale — list your drops to recover valid ids.
revision_conflict 409 not retryable The drop changed under you. Re-read current_revision (carried on the error), then retry with it as if_revision.
Workspaces & teams
workspace_not_found 404 not retryable The slug or id doesn't match a workspace you can reach. List your workspaces to see valid slugs.
workspace_choice_required 409 not retryable Publish couldn't resolve a workspace automatically. The body carries choices[] — pick one and set it active (or pass workspace).
workspace_mismatch 409 not retryable The resource belongs to a different workspace than the key targets. Target the right workspace.
workspace_pinned 400 not retryable A service key can't switch workspaces — it's pinned at mint. Use a delegated key to switch.
sole_owner_of_team 409 not retryable You can't delete your account while you're the sole owner of a team. Transfer ownership or delete the team first.
Uploads & publish-by-reference
checksum_mismatch 422 not retryable Uploaded bytes don't match the manifest checksum. Re-upload the file.
upload_expired 409 not retryable The staged upload session expired. Start a new one.
remote_fetch_failed 422 not retryable The server couldn't fetch a per-file source_url. The body's failures[] lists each { path, source_url, reason } — fix the URL or inline the bytes.