API reference
Errors
Error codes and handling for the Setback API.
Error format
All errors return a consistent JSON structure:
{
"error": {
"code": "not_found",
"message": "Document not found",
"status": 404
}
}HTTP status codes
| Status | Description |
|---|---|
| 200 | Success |
| 400 | Bad Request — invalid parameters |
| 401 | Unauthorized — missing or expired sign-in token |
| 403 | Forbidden — your plan does not include this endpoint |
| 404 | Not Found — resource does not exist |
| 429 | Too Many Requests — rate limit exceeded |
| 500 | Internal Server Error |
Common error values
The error field is usually the status text, not a short code. For example,
it reads "Bad Request", not bad_request. The one exception is
plan_required. Its body also carries a plan field.
error value | Status | Description |
|---|---|---|
Bad Request | 400 | A query parameter or JSON body is invalid, or a required one is missing |
Unauthorized | 401 | The sign-in token is missing, invalid, or expired |
plan_required | 403 | The endpoint needs a higher plan; the plan field names it |
Not Found | 404 | The requested resource was not found |
Too Many Requests | 429 | Too many requests; wait for the Retry-After header, then try again |
Internal Server Error | 500 | An unexpected server error occurred |
Handling errors
Always check the HTTP status code first. For 429 responses, use the X-RateLimit-Reset header to determine when to retry. For 500 errors, implement exponential backoff with a maximum of 3 retries.