Errors and limits
Every error has the same shape: { "error": { "code": "…", "message": "…" } }.
| Status | Code | What it means |
|---|---|---|
| 401 | unauthorized | No token, or it is invalid or has expired (they last 5 minutes). Sign in again. |
| 403 | plan_required | This organization's plan does not include API access (Plus and Max do). |
| 403 | api_disabled | API and agent access is switched off for the organization. An owner or admin switches it on in SparkyLi, Settings, API and agents. |
| 403 | forbidden | You are not a member of this product, or your role may not do that. You can do what your role can do in the app, no more. This covers writes too. |
| 403 | plan_limit | The plan's limit is reached (for example invoices per month or contacts). |
| 400 | bad_request | The body is not a JSON object, or a field is missing or wrong. The message names the field. |
| 413 | too_large | The body is larger than 64 KB. |
| 400 | org_required | You belong to several organizations. Add the x-sparky-org header (ids are in /me). |
| 404 | not_found | There is no such record, or it is not yours to see. |
| 429 | rate_limited | More than 60 reads or 10 writes in a minute. Wait a minute. |
Limits
- 60 reads a minute and 10 writes a minute per person or app.
- Lists return up to 100 records; use offset and next_offset to page.
- Every call is recorded: the route, when and who, never the data.
- Tokens last 5 minutes. Switching API access off for the organization stops everything at once.