Error codes

View Markdown

An error response. error.code names the error and is stable; branch on it, since several codes share a status. error.message is for people and may change.

error.details, when present, takes one of three shapes:

A list of {field, message}, on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal. field can be a path such as widgets[1].id or check_ins.<slug>, or base for the record as a whole, and the same field can appear more than once.
{required_scope, token_scopes}, on insufficient_scope: the scope the operation needs, and the scopes the token has.
{merged_into, location}, on fault_merged: the fault it was merged into. Only writes get this; reads of a merged fault redirect to it with a 301.

Every 429 sends a Retry-After header with the seconds to wait. A 503 can be retried after a short wait.

Include meta.request_id when contacting support.

`error.code`	Status	Meaning
`invalid_parameter`	400	A query parameter is malformed or outside its allowed values.
`unauthorized`	401	The credential is missing, invalid or revoked.
`unsupported_auth_scheme`	401	The credential was sent with HTTP basic auth instead of as a Bearer token.
`credential_in_query`	401	The credential was sent in the URL.
`ingestion_key_not_accepted`	401	An ingestion key was sent; this API takes an API token.
`access_denied`	403	The credential isn’t allowed to do this to this record.
`insufficient_scope`	403	The token lacks a scope this needs. `details` names it.
`project_restricted`	403	A token limited to some projects can’t create projects.
`requires_user_token`	403	This records who acted, so it needs a user token, not an account token.
`feature_unavailable`	403	The plan doesn’t include this.
`limit_reached`	403	The plan’s limit for this resource is reached.
`account_inactive`	403	The account isn’t active.
`account_parked`	403	The account is parked.
`not_found`	404	Doesn’t exist, or isn’t visible to this credential.
`fault_merged`	409	The fault was merged into another. `details` names it.
`validation_error`	422	The body is invalid. `details`, when present, names each field.
`forbidden_attributes`	422	The body sets fields that can’t be set.
`ambiguous_account`	422	The credential covers more than one account.
`delete_failed`	422	The delete didn’t complete.
`rate_limit_exceeded`	429	Over the rate limit. Wait for `Retry-After`.
`concurrent_request`	429	Another request is changing the same thing. Retry.
`streams_provisioning`	429	The project’s Insights streams are still being set up. Retry.
`maintenance_mode`	503	Writes are paused for maintenance. Retry later.
`service_unavailable`	503	Temporarily unavailable. Retry shortly.