API errors
Errors use one shape:
{ "error": { "code": "entitlement_required", "message": "A complete sentence you can show to people.", "fields": {} } }Some older routes return { "error": "<message>" }. Read error.code when it is there, and fall back to the message.
| Status | Code | Meaning | Fix |
|---|---|---|---|
| 400 | invalid_body |
Unknown or invalid fields | Check the request against the endpoint. |
| 400 | label_required |
A source key needs a label | Send label. |
| 401 | none | No credentials, or they were refused | Send Authorization: Token ewt_…, or sign in again. |
| 403 | none (“Insufficient permissions”) | Your role or token scope doesn’t allow it | Use a token with the scope, or ask an Admin. |
| 403 | entitlement_required |
Your plan doesn’t include feature |
See Plans and features. |
| 404 | *_not_found |
Unknown ID, or it belongs to another organization | Check the ID. |
| 409 | not_in_catalog, version_not_approved |
A baseline member isn’t in the catalog or approved | Add or approve it first. |
| 409 | revision_published |
Published revisions can’t change | Edit the next draft. |
| 409 | sso_setup_incomplete |
SSO federation isn’t finished | Contact support. |
| 429 | refresh_rate_limited and others |
Too many requests | Wait for Retry-After. |
API tokens can’t create tokens. That request answers 403 with “API tokens cannot create tokens. Sign in to create one.”