#Error Handling
All API errors return a consistent JSON structure with an HTTP status code, error type, and human-readable message.
Error response
json
{
"error": {
"type": "validation_error",
"message": "Field 'name' is required",
"status": 400
}
}
#Status Codes
| Code | Meaning | Common Cause |
|---|
| 400 | Bad Request | Invalid JSON, missing required fields |
| 401 | Unauthorized | Missing or expired token |
| 403 | Forbidden | Insufficient permissions or scope |
| 404 | Not Found | Resource does not exist |
| 409 | Conflict | Duplicate resource (e.g., vault name) |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Error | Server-side error |
| Header | Description |
|---|
| X-RateLimit-Limit | Maximum requests per window |
| X-RateLimit-Remaining | Requests remaining in current window |
| X-RateLimit-Reset | Unix timestamp when the window resets |
| Retry-After | Seconds to wait (only on 429 responses) |
