API request is returning 401, 403, 409, 422, or 429

Overview

• 401 usually means missing, invalid, revoked, or expired API key.
• 403 usually means authentication succeeded but required scope/entitlement is missing.
• 409 commonly represents idempotency/conflict conditions; read the Problem Details rather than blindly retrying with a new key.
• 422 means request validation failed and the input needs correction.
• 429 can come from the per-key 100 requests/minute window or the Business plan's daily API allowance.
• MiniTill uses Problem Details and rate-limit/reset headers to make these cases distinguishable.

When to use this

• Use this whenever an external integration stops even though the endpoint itself is documented as public.

Step-by-step

1. Record status plus Problem Details type/detail/code.
2. 401: verify full X-Api-Key, active status, expiry, and Business.
3. 403: verify required scope and API plan entitlement.
4. 409: inspect Idempotency-Key/body/processing state and Retry-After.
5. 422: fix the invalid fields.
6. 429: inspect both X-RateLimit-* and X-Daily-RateLimit-* headers.
7. 500/transient errors: retry with bounded backoff and the same idempotency key for the same mutation.

Common mistakes

• Do not rotate API keys for a 422 validation problem.
• Do not create extra keys to bypass the Business daily API allowance.
• Do not use a new Idempotency-Key for the same uncertain mutation retry.

Troubleshooting

• If the endpoint is absent from current OpenAPI/API Reference, verify that it is actually public-ready.
• If a previously working key suddenly returns 401, check expiry/revocation/Business subscription before changing code.