Error codes

When the Clavian API refuses a request, it answers with a problem document (RFC 9457), and the document’s type is the address of one of these pages. Each page says what the failure means and what a client should do about it.

Branch on code: it names the failure and never changes. There are 47 codes, grouped here by the HTTP status each is sent with.

Codes by status

400 Bad Request

The request could not be understood as written, and has to change before it is sent again.

• Validation failedvalidation_failed
• Incorrect codeotp_invalid
• Code expired; ask for a new oneotp_expired
• This phone number cannot be usedphone_number_refused
• Accept the terms and the privacy policyconsent_required
• Incorrect PINstaff_pin_incorrect

401 Unauthorized

The request came with no session, token or API key the API accepts.

• Not signed inunauthenticated
• Incorrect email or passwordinvalid_credentials

402 Payment Required

Something has to be paid for first: a session’s funding, or a capability the organisation’s plan does not include.

• Nothing to fund the sessionno_funding
• Not included in the planentitlement_required

403 Forbidden

The caller is known, and may not do this: its role, a rule of the venue or a ban stops it.

• Not allowedforbidden
• Player is bannedplayer_banned
• ID check requiredid_check_required
• Age restrictedage_restricted
• Email address not verifiedemail_not_verified
• Sign in again to do thisreauthentication_required
• Second factor requiredsecond_factor_required
• Invitation is for someone elseinvitation_contact_mismatch
• This counter device is lockeddevice_locked
• PIN locked; a manager must reset itstaff_pin_locked
• Not on a shared counter deviceshared_device
• Setting lockedsetting_locked

404 Not Found

Nothing the caller may see is there. It is also the answer wherever saying that something exists would reveal it.

• Not foundnot_found

409 Conflict

The request conflicts with the current state: something changed first, or is already so.

• Conflictconflict
• Session already endedsession_already_ended
• Station not availablestation_unavailable
• Station reservedstation_reserved
• Already in a sessionalready_in_session
• The terms or privacy policy have changedconsent_version_outdated
• That email address or phone number is on another accountcontact_in_use
• Price changedprice_changed
• Discount limit reacheddiscount_limit_reached
• Invitation used, revoked or expiredinvitation_unavailable
• Already a memberalready_a_member
• An organisation needs an ownerlast_owner
• That role name is takenrole_name_taken
• This organisation has as many custom roles as it maycustom_role_limit_reached
• Role still in userole_in_use
• That slug is takenslug_taken

412 Precondition Failed

The update was based on a version of the resource that is no longer current.

• Stale writestale_write

422 Unprocessable Content

The request is well formed, and cannot be carried out as asked.

• Cannot be processedunprocessable
• Profile incompleteprofile_incomplete
• Idempotency key used for a different requestidempotency_key_reused
• Currency differs from the organisation'scurrency_mismatch

429 Too Many Requests

Too many requests in the current window. Retry-After says how long to wait.

• Too many requestsrate_limited

500 Internal Server Error

The API failed, and nothing the request would have changed was kept.

• Something went wronginternal_error

503 Service Unavailable

A service the API depends on cannot do its part right now.

• Codes cannot be sent right nowotp_delivery_unavailable

The problem document

Every error response of the API has this shape, as application/problem+json. Its schema is Problem in the OpenAPI document, which also says which codes each endpoint can answer with.

type

The address of the failure’s page here, which says what it means and what to do.

title

A short summary of the failure. The same for every occurrence of a type, and not translated.

status

The HTTP status of the response, repeated.

detail

What went wrong this time, for people to read. It changes from one occurrence to the next, and never says whether an account exists. Optional.

code

The failure in snake case: the member a client branches on. It never changes for a failure.

requestId

The request’s id: also its X-Request-Id header and its trace id. Quote it to support.

errors

For a validation failure, one entry for each field that failed: its field, a code and a message. Optional.

instance

A reference to this occurrence, where the API gives one. Optional.

Answers from /v1/auth/

The sign-in endpoints under /v1/auth/ answer in a shape of their own instead, { "code", "message" }, with the code in upper snake case. The OpenAPI document calls it AuthError; its codes have no pages here.