application/problem+json body, with one exception noted below. code is the machine-readable value - stable across releases, safe to switch on in client code. type is a URI that resolves to this page’s anchor for that code - this member is the documentation link.
Problem anatomy
RFC 9457 problem details, the body of every error in this API except the legacy 429 described below.code is the value to branch on; type resolves to its section on this page.
Legacy error body
The one error body in this API that is not problem+json: the per-IP rate limit’s 429 on routes outside the dock-control plane, such asPATCH /api/docks/{id}. { "error": "Too many requests" }, with Retry-After. Every other error is application/problem+json.
Error catalog
Validation failed
Code:validation_failed · Status: 400 · field member: sometimes present
The request body or parameters did not pass validation: a required field was missing, a value was out of range, or an enum value was not recognized.
Check the detail member for the specific problem, fix the request, and resend it.
Unauthorized
Code:unauthorized · Status: 401 · field member: never present
The request carried no credential, or the credential it carried was missing or invalid.
Send a valid Authorization: Bearer credential and retry.
Forbidden
Code:forbidden · Status: 403 · field member: sometimes present
The credential was valid, but does not carry permission for this action; for example, a non-admin member trying to change org settings.
Use a credential with the required role, or ask an admin to perform the action.
Demo mode is read-only
Code:demo_read_only · Status: 403 · field member: never present
This request would mutate data, but the current session is a demo session, and demo sessions cannot write.
Sign in with a real account to perform this action.
Not found
Code:not_found · Status: 404 · field member: never present
The resource named in the request path does not exist, or exists but is not visible to this credential.
Check the id in the path. A resource outside your visibility scope also reports as not found, not forbidden.
Conflict
Code:conflict · Status: 409 · field member: sometimes present
The request conflicts with the resource’s current state; for example, adding a member who already belongs, or reusing a value that must be unique.
Check the detail member for the specific conflict and adjust the request; this is not something a bare retry fixes.
Invite expired
Code:invite_expired · Status: 410 · field member: never present
The invite this request references is past its expiry window and can no longer be redeemed.
Ask whoever sent the invite to send a new one.
Too many requests
Code:rate_limited · Status: 429 · field member: never present
Too many requests in a short window: more than 30 mutating requests from one IP in 10 seconds; more than 120 command reads from one IP in 10 seconds, 1,200 for one organization in a minute, or 600 for one API key in a minute; more than 30 sandbox reads from one IP in 10 seconds; or, for dock commands, more than 6 commands to one dock, 30 from one organization or 15 from one API key in a minute.
Back off and retry. Honour Retry-After when it is present: every read limit, every per-IP limit and every per-key limit sends it; the per-dock and per-organization command limits do not — and the per-dock one is a physical cycle time, not a quota to work around.
Internal server error
Code:internal_error · Status: 500 · field member: never present
Something went wrong on the server that was not anticipated by the request-handling code.
Retry with backoff. If it persists, the failure has already been recorded on our side; contact support with the time of the request.
Temporarily unavailable
Code:temporarily_unavailable · Status: 503 · field member: never present
A dependency this request needs is not currently configured or reachable, so the request is refused rather than served incorrectly.
Retry with backoff. This is a fail-closed condition on our side, not something your request can fix.
Dock is busy
Code:dock_busy · Status: 409 · field member: never present
A dock runs one command at a time, and this dock already has a command in flight.
Back off and retry later with a FRESH Idempotency-Key; reusing the same key just replays into the same busy dock.
Idempotency key reused with different parameters
Code:idempotency_key_reused · Status: 409 · field member: never present
The same Idempotency-Key was sent with a request the dock-control executor had already reserved that key for, with different parameters. Neither Outpost server raises this any more: a reused key carrying a different command is treated as a new command on both.
Use a new Idempotency-Key for a genuinely different request. Resend the ORIGINAL body unchanged if you’re retrying the same request.
Command channel unavailable
Code:command_unavailable · Status: 503 · field member: never present
The channel this command would travel through is not currently available, so the command was refused rather than accepted and silently dropped.
Retry with backoff.
Stale command result
Code:stale_result · Status: 409 · field member: never present
This command already has a different completion event recorded against it. Each command is resolved exactly once, and a second, conflicting outcome is rejected rather than overwriting the first.
Read the command’s own resource to see the outcome that was recorded. A result that simply arrives late is not an error and does not return this code — it is accepted as long as nothing has resolved the command yet.
Camera unavailable
Code:camera_unavailable · Status: 503 · field member: never present
The dock’s camera could not produce a live video answer — the connection to it failed, or the WebRTC handshake itself failed or timed out.
Retry with backoff. If it persists, the dock may be offline or its camera module may be down.