Operations
Troubleshooting
Symptoms, causes and fixes for the problems developers meet most often.
Start with the status code, the error type and the request ID. The API keys page lists your recent requests with their status.
| Symptom | Likely cause | Fix |
|---|---|---|
401 "Send your API key in the Authorization header" | Header missing or misspelt; some tools drop it on redirects. | Send Authorization: Bearer qk_…; call the exact https://…/api/v1/… URL (no redirect). |
401 "This is not a Quilo API key" | Extra spaces, quotes or a line break around the key; key cut off when copying. | The key is exactly 46 characters starting with qk_. Copy it again or create a new one. |
401 "not valid" | Wrong key, or a key from another Quilo installation. | Create a new key in the right Quilo. |
401 "revoked" / "expired" | Someone revoked it, or it ran out. | Create a new key; set a reminder before the next expiry. |
403 insufficient_scope | Read-only key used for POST, PATCH or DELETE. | Create a Read and write key. |
403 permission_denied on everything | API access switched off, account suspended, or the key's owner left the company. | Ask an owner or admin; create the key with an active member's account. |
403 permission_denied on writes only | Trial ended or subscription cancelled (read-only workspace), or the role may not delete. | Owner chooses a plan; use a manager, admin or owner key for deletes. |
404 for a record you can see in the app | The record is in another company, or in a brand your account cannot access. | Use a key created in that company by someone with access to that brand. |
404 "no such endpoint" | Typo in the path, or missing /api/v1. | Compare with the API reference. |
422 "is not a field of this resource" | Typo (firstname), or a field from another resource. | Use the exact field names from the reference. |
422 "brand_id … is not a brand you can access" | Wrong brand ID, archived brand, or staff limited to other brands. | Get valid IDs from GET /api/v1/me. |
422 "must be an ISO 8601 date-time with time zone" | Time sent without Z or +02:00. | Send 2026-10-20T14:00:00+02:00. |
409 conflict on a sale | The receipt number already exists in that brand. | GET /sales?receipt_no=… and update it instead. |
409 "Idempotency-Key was already used" | Same key reused for a different body. | Use a unique key per record you create. |
429 rate_limited | Over 120 requests a minute for this key. | Wait Retry-After; use limit=200 and incremental syncs. |
| Browser shows a CORS error | The API was called from browser JavaScript. | Call it from your server; never expose keys in a page. |
| Times look two hours off | Quilo returns UTC. | Convert to Europe/Zurich (or your time zone) when displaying. |
500 server_error | A problem on Quilo's side. | Retry with backoff; if it persists, contact support with the request ID. |
Still stuck? See Support.