Errors · Developers

A refused request answers a 4xx or 5xx status with a small JSON body. error is a machine code your system switches on; error_description, where present, is a fixed English sentence for the person reading a log.

A refusal

{
  "error": "invalid_request",
  "error_description": "limit is invalid"
}

invalid_transition also carries current_status, the state the record is in.
validation_failed also carries fields, the name of each field the product’s own form would refuse.
A write refused for any reason has changed nothing.

Every code

Error codes
Status	Code	When
400	`idempotency_key_required`	The write has no Idempotency-Key header of 1 to 255 characters.
400	`invalid_request`	A query parameter is invalid, or a write’s body is not a JSON object.
400	`unsupported_grant_type`	The grant type is not client_credentials.
401	`invalid_client`	Client authentication failed: an unknown client_id, a wrong secret, a revoked credential or another Organisation’s, or API access is not Full.
401	`invalid_token`	The token is missing, invalid, expired or revoked, of another Organisation, or API access is not Full. Ask for a new token.
403	`approval_limit_exceeded`	The amount is above the run-as Administrator’s approval limit.
403	`forbidden`	The run-as Administrator lacks the permission, or the record is outside their Data Access Rules.
403	`https_required`	The request was sent over plain HTTP and was not processed.
403	`insufficient_scope`	The credential does not hold the scope the route needs.
403	`run_as_disabled`	The credential has no run-as Administrator, or that person is no longer one.
404	`module_disabled`	The Organisation has the module this route belongs to turned off.
404	`not_found`	An unknown host or path, or an id that is unknown, deleted or of another Organisation.
405	`method_not_allowed`	The method is not served on this path. `Allow` lists what is: `GET, HEAD` on a read path, `POST` on /oauth/token, the write’s own method on a write path.
409	`conflict_declared`	The Assessor has declared a conflict of interest with an application.
409	`file_not_scanned`	The file has not finished its malware scan; try the attach again shortly.
409	`idempotency_in_progress`	The first request with this Idempotency-Key has not finished. Nothing was written; retry after the given seconds.
409	`invalid_state`	The record is not in a state that admits this write.
409	`invalid_transition`	The move is not open from where the record stands; `current_status` says where that is.
412	`precondition_failed`	If-Match is missing, malformed or not the record’s current lock_version, or the record changed under the write. Nothing was written.
413	`payload_too_large`	The body, or the declared file, is larger than the limit that applies.
415	`unsupported_media_type`	The body is not application/json, or the target does not accept the file’s content type.
422	`file_infected`	The file failed its malware scan and was not attached.
422	`idempotency_key_reused`	The Idempotency-Key was used in the last 24 hours for a different method, path or body.
422	`unknown_field`	The body has a property the route does not document; the first is named.
422	`unknown_tag`	A tag is not one of the Organisation’s tags. None is created.
422	`validation_failed`	Body values the product’s own form would refuse; `fields` names each.
429	`rate_limited`	A rate limit was exceeded: 120 requests a minute per credential, 30 token requests a minute per client_id.
500	`server_error`	An unexpected server error.
503	`temporarily_unavailable`	The Organisation’s API access cannot be determined, or a dependency is unavailable. Retry after the given seconds.

Which to retry

429 rate_limited, 503 temporarily_unavailable and 409 idempotency_in_progress carry Retry-After: wait that many seconds and send the same request again, with the same Idempotency-Key for a write.
500 server_error: retry a read later. Retry a write with the same Idempotency-Key, so that a write that did happen is answered again rather than made twice. See the idempotency guide.
401 invalid_token: ask for a new token, then retry.
Anything else is about the request itself: change it before you send it again.

The OData reporting feed answers its own query errors in the OData error body: 400 bad_request, 404 not_found, 410 delta_token_expired, 501 not_implemented. See Power BI and Idempotency.