Help · Errors

API error codes

Every error the API returns carries a code, a detail sentence for people and a request_id. Scripts and assistants should act on the code; the type link in the answer leads to its entry here.

Validation failed

validation_failed · HTTP 422

Something in the request is missing or not in the form this endpoint accepts. detail names the problem, and issues lists each field when the body itself did not fit.

What to do: Correct the request and send it again. The same request gives the same answer.

Authentication required

unauthenticated · HTTP 401

The request did not say who is asking, or what it said no longer works: no session, an expired one, or a token that was revoked or ran out.

What to do: Sign in again in the browser. A script or an assistant sends a fresh token as Authorization: Bearer <token>, made under Account → Security.

Not allowed

forbidden · HTTP 403

The API knows who is asking, and the answer is still no: the role does not allow it, the request came from another site, or the action needs a fresh confirmation.

What to do: When the body says "reason": "step_up_required", confirm it is you with a passkey, a recovery code or an emailed code, then try again. Otherwise ask an owner or admin of the team for a role that allows it.

Not found

not_found · HTTP 404

There is nothing here that you may see. It may not exist, or it may belong to a team you are not part of. The answer is the same either way, on purpose, so it tells nobody what other teams have.

What to do: Check the address or the id. If somebody sent you the link, ask them to invite you.

Conflict

conflict · HTTP 409

The change does not fit the current state: a name or address is already in use, or somebody changed the same thing at the same moment.

What to do: Read the current state, then decide again. detail says what is in the way.

Precondition failed

precondition_failed · HTTP 412

The version you said you were changing (If-Match) is no longer the current one: it was saved again after you read it.

What to do: Fetch it again, apply your change to the new version, and send that.

Too many requests

rate_limited · HTTP 429

Too many requests arrived from you in a short time.

What to do: Wait the number of seconds in the Retry-After header, then try again.

Limit reached

quota_exceeded · HTTP 409

A fixed limit is reached, such as how many projects a team may have. Waiting does not change it, and the body says which limit and by how much.

What to do: Remove something you no longer need, or ask whoever runs this Studio for a higher limit.

Payload too large

payload_too_large · HTTP 413

The body or the upload is bigger than this Studio accepts for this request.

What to do: Send a smaller file, or split the work into smaller requests.

No longer available

gone · HTTP 410

It was here and has been removed for good, for example an export the retention sweep deleted. Asking again will not bring it back.

What to do: Make it again. For an export, press Export everything once more.

Could not be completed

unprocessable · HTTP 422

The request was fine, but the work it asked for could not be done, for example an export that failed. detail says why.

What to do: Fix what detail names, then start the work again.

Upstream provider failed

upstream_failed · HTTP 502

A service this Studio relies on, such as a hosting provider or a git host, failed or refused.

What to do: Check that service and the credential stored for it, then try again. Nothing in your request was wrong.

Temporarily unavailable

unavailable · HTTP 503

This Studio cannot serve the request right now, for example because a service it needs is not set up or is restarting.

What to do: Try again in a minute. If it keeps happening, tell whoever runs this Studio and quote the request_id.

Something went wrong

internal_error · HTTP 500

Something failed that this Studio did not expect. The answer says no more, on purpose, so nothing internal leaks.

What to do: Try once more. If it fails again, send the request_id to whoever runs this Studio: it points to the full record in their logs.

Fields some errors carry

Besides code, title, status, detail and request_id, an error may carry one of these. New fields may be added; ignore the ones you do not know.

issueswith validation_failed: One entry per field the body got wrong, each with its path (the field), code and message. Present when the body did not fit its schema; absent when a rule after the schema refused it, which detail then names.
scopewith forbidden: The kind of token that was refused: read on a write, write on something only a person at a screen may do, agent for an assistant’s token. Another credential, or a person in the dashboard, can do it; the same token never will.
reasonwith forbidden, conflict: Why, when the code alone does not say. step_up_required: confirm it is you, then try again, in a signed-in browser (methods lists the ways open to you). scheduled_for_deletion: the team or project is being deleted, so it only reads until the deletion is cancelled. domains_still_here: a moved project still serves its domains (domains lists them); send still_served: true to delete it anyway. invite_other_account and invite_needs_sign_in: the invitation is for another address, or for one that must sign in first.
limit, used, maxwith quota_exceeded, payload_too_large, validation_failed: Which limit was reached (limit, a name such as projects, upload_bytes or api_token_days), how much is in use when that is counted (used), and the most allowed (max). A team’s usage against its limits is at GET /api/v1/accounts/{team}/usage.
grantswith forbidden: On minting a token with a token: the grants the new token asked for that the one minting it does not carry.