API authentication and error responses

Overview

• Public API requests authenticate using the X-Api-Key HTTP header.
• Keys are Business-scoped: a valid key cannot use IDs to escape into another Business's data.
• Public API error responses use RFC 7807-style Problem Details.
• Typical meanings are 400 malformed request/query, 401 missing/invalid key, 403 insufficient scope/permission, 404 resource not found, 409 conflict/idempotency conflict, 422 validation, 429 rate limit, and 500 server error.
• Do not retry every error the same way: validation/scope problems require correction, while selected transient failures can use backoff.

When to use this

• Use this as the first diagnostic guide when an otherwise supported API endpoint rejects a request.

Step-by-step

1. Send X-Api-Key on every public API request.
2. On error, record HTTP status plus Problem Details type/title/detail/code where present.
3. For 401, verify the full key/expiry/revocation.
4. For 403, verify scope/entitlement.
5. For 409, inspect conflict/idempotency semantics.
6. For 422, fix request data.
7. For 429/500, follow headers/backoff instead of immediate tight-loop retries.

Common mistakes

• Do not put the key in a URL query string.
• Do not convert every non-2xx response into a generic 'MiniTill offline' message.
• Do not retry 422 validation requests without changing the input.

Troubleshooting

• If the prefix in Back Office looks correct but authentication fails, remember the prefix is only an identifier, not the complete secret.
• If 403 persists after adding a scope to a different key, confirm the application is actually using the newly issued credential.