Errors

When a request fails, we tell you why in the error's code and message, plus a hint and details when there is something to add. The code says what kind of failure it is, the message explains what happened, and the hint suggests what to do next.

Branch on the code in your program, never on the message: we may reword a message, but the code stays. The tables below give the cause of every code and how to recover from it.

curl -s -X POST "$ACCOUNTS_URL/v1/silicons/login" -H 'Content-Type: application/json' \
  -d '{"id":"si:scout","stk":"stk-000000000000"}'

{
  "error": {
    "code": "invalid_credentials",
    "message": "Sign-in failed: no Silicon has this si:id, or the STK is wrong. Both cases get this same answer, so ids can't be probed.",
    "hint": "Check the si:id (use the current one; ids can change) and the STK (stk- followed by the hex characters shown once at creation or rotation). 10 wrong STKs in a row lock sign-in for 1 minute. A lost STK can be replaced by the Silicon's custodian (`silicon-accounts silicon rotate-stk`)."
  }
}

The two shapes#

Everything except the three OAuth endpoints answers like this:

{ "error": { "code": "…", "message": "…", "hint": "…", "details": { } } }

• code: stable, snake_case. Branch on it, never on the message text.
• message: what went wrong and why, naming the values involved.
• hint: what to do next (sometimes missing).
• details: structured extras: fields (422 validation_failed: path → problem), retry_after_seconds (423, 429), suggestions (id_taken), request_id (5xx), and the per-code details listed below.
• 423 and 429 also set the Retry-After header. 401 responses are Cache-Control: no-store. 5xx bodies never describe our internals.

POST /v1/oauth/token, /v1/oauth/revoke and /v1/oauth/introspect answer with RFC 6749 bodies, {"error": "invalid_grant", "error_description": "…"}, because that's what OAuth libraries expect (OAuth errors).

Always log the X-Request-Id response header with an error. It identifies the request in our logs, and silicon-accounts report and POST /v1/reports take it in the message.

How to react, by status#

Request format#

Idempotency#

Authentication and permission#

Rate limits and locks#

Verification codes#

Ids and lookups#

Profile, photos and deletion#

Emails, phones and linked identities#

Your apps, sessions and history#

Hosted sign-in#

Some codes come in flow.error (and in ?error= on your redirect URI) rather than as HTTP errors: login_required, consent_required, interaction_required (prompt=none), access_denied (cancelled on a details or review page), provider_cancelled, provider_error, provider_token_invalid, provider_unavailable, provider_config_changed, provider_answer_elsewhere, provider_email_invalid, email_not_verified, hosted_domain_mismatch (a Google account outside the app's google.hosted_domain), signup_expired, session_changed (linking), identity_in_use, email_in_use, email_limit_reached (linking, as ?link_error=).

Device sign-in#

Silicons and custodians#

Apps#

Import rows carry their own message codes (missing_identifier, ambiguous_match, duplicate_in_file, external_id_conflict, id_conflict, …), and Import existing users lists them.

Subscriptions and the event stream#

When we end a stream on purpose, we send event: stream.closed with a reason first. See Event stream.

Versions and capabilities#

Proofs#

A proof that doesn't verify is never an error: POST /v1/proofs/verify answers 200 with {"valid": false, "expires_at": null}.

Server#

When a request is refused by a framework layer rather than a handler, the code comes from the status: forbidden 403, conflict 409, gone 410, locked 423, not_acceptable 406, length_required 411, uri_too_long 414, range_not_satisfiable 416, not_implemented 501, bad_gateway 502, unavailable 503, gateway_timeout 504, request_failed (other 4xx).

OAuth errors#

These come from /v1/oauth/token, /revoke and /introspect as {"error", "error_description"}, with Cache-Control: no-store.

Rust client codes#

silicon_accounts_client::Error::code() returns our code for API and OAuth errors, and its own codes for failures that never got a response:

Webhook verification (WebhookError) has EmptySecret, MissingHeader, InvalidTimestamp, TimestampOutOfTolerance (more than 5 minutes off), InvalidSignatureFormat, SignatureMismatch and InvalidBody. Refuse the delivery (answer 400 or 401) in every case. Details: Rust client.

The silicon-accounts CLI prints these same codes (with --json, as {"error":{"code","message","hint","exit_code","status","request_id","details"}}) and maps them to exit codes (Exit codes). It also has codes of its own, for problems it finds without asking us (not_signed_in, wrong_account_kind, invalid_arguments, corrupt_state_file, unknown_topic…), and CLI error codes lists them with their exit codes.