Developers
Errors
The one error envelope, every code it can carry, and what to do about each.
Every 4xx and 5xx response has the same body:
{
"error": {
"code": "insufficient-scope",
"message": "this key does not have the insights:read scope",
"requestId": "6f1c2e0a-3b7d-4a2e-9c1f-0d8e7b6a5c43"
}
}code is stable and meant for your code. message is for a person and its wording may change. requestId matches the X-Request-Id header on the same response; quote it when you report a problem.
Codes
| Status | Code | Cause | What to do |
|---|---|---|---|
| 401 | unauthorized | No bearer token, or an unknown or revoked key. | Check the key; create a new one if it was revoked. |
| 403 | insufficient-scope | The key is valid but lacks the endpoint's scope. | Create a key with that scope. |
| 403 | plan-api-off | The workspace's plan does not include API access. | Not a key problem; the plan needs the feature. |
| 429 | rate-limited | The key's bucket is empty. | Wait the Retry-After seconds. See Rate limits. |
| 409 | conflict | The object's state refuses the write, such as answering a follow-up that is already closed. | Read the object again; the work is done or no longer applies. |
| 409 | idempotency-mismatch | The Idempotency-Key was already used for a different request. | Use a fresh key for a new request. |
| 400 | invalid-range | from or to is not a day, to is before from, or the range is over 366 days. | Fix the parameters. |
| 500 | internal_error | Something failed on ShowPilot's side. | Retry once; if it persists, report the request id. |
Good to know
- A 401 never means the plan. Plan problems are always the 403 with
plan-api-off, so a tool can show the right message. - Every write takes an
Idempotency-Key. Any unique string you choose; the same key with the same request replays the stored response withIdempotent-Replayed: true, a bodyless delete included. The two query POSTs under knowledge read and need no key. - Retrying is always safe. Reads change nothing. Writes take an
Idempotency-Key; a retry with the same key and the same request replays the first response instead of writing twice, and the replay carriesIdempotent-Replayed: true.