Docs/Resources
Errors
What a failed request returns, and how to handle it.
The Solarium API returns errors in a consistent JSON shape. GraphQL requests always return 200 OK at the HTTP level. Errors appear in the errors array of the response body.
The only exceptions are 429 Too Many Requests (rate limit) and 400 Bad Request (malformed JSON or invalid GraphQL syntax), which return non-200 HTTP status codes.
Error Object
Each error has a message string. Some errors include a path array indicating which field triggered the error.
Common Errors
| Message | Cause |
|---|---|
Authentication Required. | No token or API key provided |
API Key Not Authorized For This Organization. | API key belongs to a different organization |
Organization Not Found. | Invalid organizationId |
Not A Member Of This Organization. | JWT user is not a member of this organization |
API Keys Cannot Perform Admin Operations. | API key used for an admin-only mutation (e.g. managing members) |
Must Be Owner Or Admin. | Insufficient role for this operation |
Rate Limit Exceeded. 5,000 Requests/Hour. | API key exceeded hourly quota (HTTP 429) |
Mutation Errors
Mutations return a success boolean and an error string instead of throwing. A failed mutation returns success: false with a human-readable error. The HTTP status is still 200.
Example
Request
# Successful mutation
mutation {
createAccount(
organizationId: "a1b2c3d4-..."
name: "Office Supplies"
accountType: "expense"
classification: "expense"
) {
account { id name }
success
error
}
}Response
# GraphQL-level error (in errors array)
{
"errors": [
{
"message": "Authentication Required.",
"path": ["createAccount"]
}
],
"data": { "createAccount": null }
}
# Mutation-level error (success: false)
{
"data": {
"createAccount": {
"account": null,
"success": false,
"error": "Account with this name already exists."
}
}
}
# Rate limit error (HTTP 429)
{
"errors": [
{ "message": "Rate Limit Exceeded. 5,000 Requests/Hour." }
]
}