Error Handling
Athena response envelope and common error classes.
Athena APIs use a standard envelope:
{
"status": "success | error",
"message": "human-readable summary",
"data": {},
"error": {}
}Common Failure Categories
| Category | Typical Status |
|---|---|
| Missing/invalid client routing | 400 / 503 |
| Auth or rights failure | 401 / 403 |
| Resource not found | 404 |
| Validation or syntax failure | 400 |
| Constraint violation | 409 |
| Timeout | 504 |
| Backend connectivity | 503 |
| Unexpected server error | 500 |
Troubleshooting Steps
- Confirm
X-Athena-Clientis set and valid. - Validate key transport header and rights scope.
- Check route availability via
/router/registryand/openapi.yaml. - Inspect client health and logs (
/health/cluster, metrics, admin stats). - For async operations, inspect backup/deferred job status endpoints.