Common errors

Every error has the same shape. Branch on error.code, never on error.message.

By status

Status	Meaning	Retry?
`400`	Invalid request	No, not unchanged
`401`	Authentication failed	No
`403`	Missing scope	No
`404`	Not visible to you	No
`409`	Conflict, or idempotency key reused with a different payload	No, investigate
`412`	Stale `If-Match`	Yes, after re-reading
`429`	Throttled	Yes, with backoff
`5xx`	Unexpected failure	Yes, with backoff

By code

Code	Meaning	Fix
`MissingApiVersionParameter`	No `api-version` on a Management call	Add `?api-version=2026-08-30`
`UnsupportedApiVersionValue`	That version is not served here	Use a version from the message
`validation_error`	The request body did not validate	Read `error.target` and `error.details`
`not_found`	Not visible to this caller	Check the identifier, tenant and environment
`conflict`	Cannot be reconciled with current state	Read the message; do not blind-retry
`precondition_failed`	Your `If-Match` was stale	Re-read, re-apply, retry
`issuer.not_ready`	The issuer has unmet requirements	Check readiness
`unauthorized`	Authentication failed	Check the key

Reading an error

{
  "error": {
    "code": "validation_error",
    "message": "The request could not be validated.",
    "target": "claims.member_number",
    "details": [ { "code": "required", "message": "This claim is required.", "target": "claims.member_number" } ],
    "innerError": { "date": "...", "requestId": "req_...", "clientRequestId": "checkout-8891" }
  }
}

target names the first thing at fault; details has the rest. innerError.requestId is what to quote when asking for help.

404 does not mean "does not exist"

It means "not visible to you". Cross-tenant and cross-environment resources report as not found rather than forbidden, because a 403 would confirm they exist.

What errors never contain

Exception types, stack traces, database errors, connection strings, Azure resource identifiers, key vault names, tokens, credential proofs, nonces, cookies, key material, or anything about another tenant's resources.

Quote x-ms-request-id instead — with it, the exact request can be found.

Edit this page on GitHub