Error Codes
Qefro REST errors typically return JSON with a machine-readable code and human message (see API ApiError shape). Always branch on HTTP status + code, not message text alone.
Short definition (citation-ready)
Qefro APIs signal failures with standard HTTP statuses and a structured error payload so clients can retry, re-authenticate, or surface RBAC problems correctly.
Common situations
| HTTP | Typical meaning | What to check |
|---|---|---|
| 400 | Bad request / validation | JSON shape, required fields |
| 401 | Unauthenticated | Missing/expired user JWT or widget token |
| 403 | Forbidden | Member lacking Admin rights or workspace grant |
| 404 | Not found | Wrong id, wrong tenant, deleted resource |
| 409 | Conflict | Idempotent replay, unique constraint, slug taken / reserved |
| 422 | Semantic validation | Business rule failed |
| 429 | Rate limited | Back off; see Rate Limits |
| 5xx | Server / upstream | Retry with jitter; check status with support |
Workspace slug codes
| Code | HTTP | Meaning |
|---|---|---|
SLUG_INVALID | 400 | Failed shape / regex rules |
SLUG_RESERVED | 409 | Name is in reserved_subdomains |
SLUG_TAKEN | 409 | Another workspace already owns the slug |
RESERVED_SUBDOMAIN_EXISTS | 409 | Super Admin duplicate reserve |
See Workspace Subdomains.
Example error payload
{
"code": "forbidden",
"message": "You do not have access to this workspace"
}
Exact code strings can evolve — log them and map conservatively in clients.
Workflow
Debug an API failure
- Read status + code — Do not parse HTML error pages.
- Confirm credential type — User JWT vs widget token vs admin.
- Confirm tenant/workspace — Ids from the correct org.
- Retry only if safe — GET/idempotent POST; not duplicate payments.
- Check logs — Tool logs / audit logs for server-side clues.
Billing / webhook note
Payment webhooks may record error_code / error_reason / error_description on failed payments. See Webhooks and Billing UI.
FAQ
Should clients show raw codes to end users?
No. Map to friendly copy. Keep codes in logs for support.
Are GraphQL errors the same?
GraphQL uses its own error array; still inspect auth headers first on 401/403 HTTP wrappers.