Errors
The error bodies and HTTP statuses of the Stacksync API, and which errors to retry
A failed request answers a 4xx status and a JSON body that names the problem.
Error body
Operations of the current conventions answer:
{ "error": "<kind of error>", "msg": "<what went wrong>", "field": "<parameter or field at fault, or null>" }| Field | Meaning |
|---|---|
error | The kind of error, stable enough to branch on |
msg | What went wrong, in plain words, for logs and people |
field | The parameter or body field at fault, when there is one |
The older operations of syncs, sync triggers, sync webhooks, sync issues and connection creation answer a body with at least error, holding the message:
{ "error": "<what went wrong>" }Each operation's page lists the statuses it answers and their body.
Statuses
| Status | Meaning | What to do |
|---|---|---|
| 400 | The request is invalid: a parameter or body field is missing, of the wrong type or out of range. With error Unexpected Error, Stacksync could not complete a valid request | Fix the request; field names the culprit. Unexpected Error is temporary: retry later |
| 403 | Authentication or permission failure. The API never answers 401 | See Authentication |
| 404 | The resource doesn't exist in this workspace and region | Check the id and the region |
| 409 | The request conflicts with the resource's state, or a request with the same Idempotency-Key is still running | Read the resource, or wait and retry |
| 422 | The Idempotency-Key was already used with a different request. Some older operations also answer 422 when the request fails validation; their pages list it | Use a new key for a new request, or fix the request |
Most answers, errors included, carry an X-Request-Id header. Quote it when you contact support.
When to retry
Retry the same request, with an increasing delay between attempts, only when:
- the answer is 400 with
errorUnexpected Error: a temporary failure on Stacksync's side; - the answer is 409 because a request with the same
Idempotency-Keyis still running.
For creates, retry with the same Idempotency-Key, so a retry never creates the resource twice. Every other error answers the same until the request changes: fix the request, the key or the region instead of retrying.
No rate limit is published.