Errors & limits

shrug.ai returns conventional HTTP status codes. 2xx means the draw succeeded; 4xx means something about the request or account needs your attention. Error responses carry a JSON body of the form:

{ "error": { "type": "<machine_code>", "message": "<human readable>" } }

Status codes

| Status | type | Cause | Fix | |---|---|---|---| | 400 Bad Request | invalid_request_error | Malformed JSON, unknown question type, input caps exceeded, or an invalid shrug.distributions block (e.g. all-zero weights, an unknown option/question name, or p_true outside [0,1]). | Correct the request body. | | 401 Unauthorized | authentication_error | API key missing, malformed, revoked, or unknown. | Fix your key — not the plan. | | 402 Payment Required | quota_exceeded | Key is valid but the account is over its free quota with no active subscription. | Subscribe — add a payment method in Billing. | | 413 Payload Too Large | payload_too_large | The request body exceeds the size limit. | Send fewer / smaller questions. | | 404 Not Found | — | Unknown route — only /v1/decisions and /v1/systemone exist. (A bare 404 with no error body.) | Check the endpoint path. |

401 vs 402: fix the key, or fix the plan

These two are the easiest to confuse and the most important to keep apart:

  • 401 — the credential is wrong. Retrying with the same key will keep failing. Check the Authorization header and that the key is still active.
  • 402 — the credential is fine; the account has exhausted the free tier. Rotating the key will not help — add a payment method in Dashboard → Billing to continue.

See Authentication for the header format and example 401/402 bodies.

Limits

The API itself does not impose a per-request rate limit — the only account-level limit is the monthly free-tier volume cap, surfaced as 402 above. Requests are bounded per call by a body-size limit (413) and server-side caps on the number of questions, options/levels, and distribution entries (400).