API Reference
Errors
Error envelope, common status codes, and OAuth-specific codes.
Standard error envelope
{
"statusCode": 404,
"error": "Not Found",
"message": "App not found",
"timestamp": "2026-05-23T16:00:00.000Z",
"path": "/api/v1/apps/missing"
}message is always a string for ad-hoc errors and an array of
strings for validation errors (from class-validator):
{
"statusCode": 400,
"error": "Bad Request",
"message": [
"redirect_uris must contain at least 1 element",
"client_name should not be empty"
],
"timestamp": "...",
"path": "/oauth/register"
}Status code catalogue
| Code | Meaning | When |
|---|---|---|
| 200 | OK | Successful read |
| 201 | Created | Successful write (DCR, etc.) |
| 204 | No Content | Session bridge, revocation |
| 302 | Found | OAuth redirects only |
| 400 | Bad Request | Validation or malformed payload |
| 401 | Unauthorized | Missing/invalid token |
| 403 | Forbidden | Token valid but scope/role insufficient |
| 404 | Not Found | Resource doesn't exist or filtered by tenancy |
| 409 | Conflict | Idempotency clash, duplicate write |
| 422 | Unprocessable | Semantic validation (e.g., entitlement mismatch) |
| 429 | Too Many Requests | Rate limit — see Retry-After |
| 500 | Server Error | Bug, file an issue |
| 503 | Service Unavailable | Maintenance window |
OAuth-specific errors
OAuth endpoints (/oauth/*) follow RFC 6749 §5.2 — body is JSON with:
{
"error": "invalid_grant",
"error_description": "Authorization code expired or unknown"
}Possible error values:
invalid_requestinvalid_clientinvalid_grantunauthorized_clientunsupported_grant_typeunsupported_response_typeinvalid_scopeinvalid_redirect_uri