Handler errors are JSON { "error": "..." } with a matching status code. Auth and quota rejections from the key layer are short plain-text bodies - branch on the status code, not the body shape.
// 400 Bad Request
{ "error": "type must be one of: multiple_choice, widget, plain" }
// 429 Too Many Requests (free tier daily cap)
Daily API quota exceeded
// 429 Too Many Requests (paid monthly pool)
Monthly API quota exceeded| Status | Meaning | What to do |
|---|---|---|
400 | Bad filter value, malformed body, expired submission token. | Fix the request; refetch the problem if the token expired. |
401 | Missing or unknown API key. | Check the x-api-key header. |
403 | Key revoked. | Issue a new key in the dashboard. |
429 | Burst limit or plan quota exceeded. | Back off. See rate limits for windows and caps. |
5xx | Something broke on our side. | Retry with backoff; check the status page. |