Common Error Codes
API routes return a small, consistent set of error codes with appropriate HTTP status codes. The public API adds key-specific codes for authentication, scope, and rate limiting.
#Purpose
Provide a reference of the error codes developers will encounter.
#Architecture
Routes return a coded error object with an HTTP status. Codes are intentionally generic to avoid leaking internal detail, while still being specific enough to act on.
The public API surfaces additional codes tied to API-key authentication and limits.
#How it works
1
Request fails validation or auth
The route returns a coded error and matching status.
2
Client inspects the code
The error code indicates the category of failure.
3
Client responds
Retry, fix input, re-authenticate, or back off as appropriate.
#Reference
#General error codes
| Code | Typical HTTP | Meaning |
|---|---|---|
| unauthorized | 401 | Not authenticated |
| forbidden | 403 | Authenticated but not permitted |
| not_found | 404 | Resource does not exist / not in your org |
| bad_request | 400 | Invalid input |
| invalid_state / bad_transition | 409 | Action not valid for current state |
| plan_limit / locked | 403/409 | Blocked by plan or lock |
| query_failed / create_failed / update_failed / delete_failed | 500 | Database operation failed |
| ai_failed | 500 | AI generation failed |
#Public-API codes
| Code | HTTP | Meaning |
|---|---|---|
| invalid_api_key | 401 | Key missing, wrong, revoked, or expired |
| insufficient_scope | 403 | Key lacks the required scope |
| rate_limited | 429 | Too many requests (about 120/min per key) |
#Implementation notes
- Codes are stable strings; branch on the code, not the message.
- forbidden and not_found are the most common in normal operation.
- Public-API codes include the required scope where relevant.
#Limitations
Known limitations
- Messages may change; codes are the stable contract.
- 500-class codes indicate server-side failures and should be retried judiciously.
#Security considerations
Security
- Errors avoid leaking internal detail by design.
- Do not surface raw server errors to end users.
- Treat repeated 401/403 as a potential misconfiguration or probing.
#Best practices
- Branch on error codes, not messages.
- Handle 401/403/429 explicitly in API clients.
- Log server errors for diagnosis, not to users.
#Related documentation
Public API
Where codes apply.
Developer Troubleshooting
Diagnosis.
Backend Architecture
How routes respond.
Still need help?
Can’t find what you’re looking for? The DevSphere OS team is happy to help.
Was this page helpful?