Errors
Every error response uses the same shape:
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Try again in 12s.",
"trace_id": "01HXYZ..."
}
}
Always log trace_id — support can resolve issues an order of magnitude faster when you include it. Errors emitted by the surveys service use the field name correlation_id instead of trace_id; the two are interchangeable for support lookups.
Status codes
| Status | Meaning |
|---|---|
400 | Malformed request — missing or invalid parameter |
401 | Missing, invalid, or revoked API key |
403 | Authenticated, but the key lacks the required scope |
404 | Resource does not exist or is not visible to this workspace |
409 | State conflict — the resource changed under you |
422 | Validation failed on a syntactically valid request |
429 | Rate-limited — see Retry-After header |
5xx | Server-side. Safe to retry with backoff. |
Error codes
| Code | When |
|---|---|
invalid_request | The body or query string failed parsing |
invalid_api_key | Key not recognized |
not_found | Resource ID does not exist |
rate_limited | Quota exhausted for this minute or day |
email_weekly_cap_exceeded | A send would exceed the team's weekly invitation budget (429). Nothing was sent; details has used, attempted, remaining, resets_at. See Email distribution › Sending limits |
email_budget_unavailable | The send budget could not be checked (503). Retry in a minute |
invalid_sending_status | The email list has already been sent or is sending (409) |
internal_error | Server-side fault — opens an internal incident |
Retry policy
Retry 429 and 5xx with exponential backoff and full jitter. Cap retries at 5 attempts. Do not retry 4xx other than 429 — the request will fail again.