Errors
One error envelope, a stable set of codes, and how to react to each.
Every failed request answers with the same JSON envelope and an appropriate HTTP status. The message is written for a human reading a log; the code is the part your integration should branch on.
json
{
"error": {
"code": "not_found",
"message": "Survey not found."
}
}Note Error codes are part of the versioned contract and will not be renamed within v1. Messages may be reworded at any time, so do not match on them.
Status codes
| Code | Status | Description |
|---|---|---|
| invalid_request | 400 | The request body or a parameter was missing or malformed. Fix the request; retrying it unchanged will fail again. |
| unauthorized | 401 | The API key is missing, malformed, deleted, or its creator lost workspace access. Check the Authorization header, then the key itself. |
| forbidden | 403 | The key is valid but lacks the access this call needs - most often a read-only key attempting a write. |
| plan_upgrade_required | 403 | The workspace owner's plan does not include API access. Upgrading the plan restores it; retrying will not. |
| not_found | 404 | No survey with that id is reachable by this key. A survey in another workspace answers the same way as one that does not exist. |
| rate_limited | 429 | Too many requests. The Retry-After response header carries the number of seconds to wait. |
| service_unavailable | 503 | The request was valid but could not be completed safely right now. No data was returned or changed, so the same request can be retried. |
Retrying
Retry only 429 and 5xx responses, and wait for the interval in Retry-After before the first retry. A 4xx other than 429 describes a problem with the request itself, so retrying it produces the same result and consumes your rate limit.