Errors
The error body, every error code the Soljio API returns with its status and cause, the headers that help, and how to respond to each.
Every error from the HTTP API is JSON with a stable machine-readable code, a human-readable message, and the ID of the request:
{
"error": {
"code": "not_found",
"message": "The requested resource was not found."
},
"request_id": "00000000-0000-4000-8000-000000000001"
}
Branch on error.code and the HTTP status. Messages are for people. A message can vary between requests, so do not parse it. Quote request_id when you contact Soljio. A HEAD request returns the same status and headers with no body.
Errors never include stack traces, payment-provider payloads, or student information.
Error codes
| Status | error.code |
Cause | What to do |
|---|---|---|---|
400 |
invalid_request |
A field, value, JSON body, cursor, query-string parameter, or Idempotency-Key is invalid |
Fix what the message names. Do not retry unchanged |
401 |
unauthorized |
The credential is missing, malformed, unknown, revoked, expired, or belongs to a suspended school | Send a valid, unexpired service token |
403 |
forbidden |
The token lacks a required scope | Create a token with the scope named in WWW-Authenticate |
404 |
not_found |
The path, operation, or record does not exist, or belongs to another school | Check the path and the ID. A foreign ID is indistinguishable from a missing one |
405 |
method_not_allowed |
The method is not supported for this path | Use a method listed in the Allow header |
409 |
conflict |
The command conflicts with the current state, or an approval is expired, used, or stale | Read the current state, then retry with a new key if the request is still wanted |
409 |
idempotency_conflict |
The Idempotency-Key was used with different input |
Reuse a key only with identical input. See Idempotency |
413 |
payload_too_large |
The body exceeds 16,384 bytes, or 524,288 bytes for import commands | Send a smaller body |
415 |
unsupported_media_type |
A POST was not sent as application/json |
Send Content-Type: application/json |
429 |
rate_limited |
A request budget was used up | Wait Retry-After seconds, then retry with the same key. See Rate limits |
500 |
internal_error |
The request could not be completed | Retry with backoff and the same key. Quote request_id if it persists |
The default messages are:
invalid_request:The request is invalid.A more specific message usually replaces it, such asUse only limit and cursor query parameters.,Limit must be an integer from 1 to 100., orProvide an Idempotency-Key of 1–128 visible ASCII characters.unauthorized:A valid service token is required.forbidden:The service token lacks a required scope.Some operations instead sayRequired scopes:followed by the missing scopes.conflict:The command conflicts with the current state.When a business rule blocks a command, the message can carry the plain-language reason the dashboard would show, and a stale approval saysThe reviewed state changed. Create a new preview.
Headers that help
| Header | Sent with | Meaning |
|---|---|---|
WWW-Authenticate: Bearer realm="soljio-api", error="invalid_token" |
401 |
The credential was not accepted |
WWW-Authenticate: Bearer error="insufficient_scope", scope="catalog.write" |
403 |
The scope, or space-separated scopes, to add |
Allow |
405 |
GET, HEAD for reads and POST for queries and commands |
Retry-After |
429 |
A whole number of seconds to wait |
X-Request-Id |
Every response | The identifier of this attempt |
Soljio does not say why a credential failed. An unknown token, a revoked token, an expired token, and a token from a suspended school all return the same 401. The missing scope is the only detail returned, and only to a caller that has proved it holds a live credential.
Order of checks
Errors come from different stages. Knowing the order helps you diagnose a failure:
- The header shape. A malformed or missing bearer header returns
401before anything else. - The path and method:
404,405. - The body and its headers:
415,413, and400, including a badIdempotency-Key. - The credential and its scopes:
401,403. - The rate limit:
429. - The operation itself:
400,404,409, or500.
Errors from stages 1 to 4 do not include a RateLimit header, because no quota was evaluated yet. See Rate limits.
Errors from agents
The MCP server does not return this JSON to an agent. A failed tool call returns a result marked as an error whose text reads code: message, for example forbidden: The service token lacks a required scope. When an agent connection has ended, the text is unauthorized: This agent connection has ended. Connect the agent again. See Agents and MCP.
Troubleshooting
- 401 on a token that looks right. Check it has not expired or been revoked or superseded, and that the header reads
Authorization: Bearer soljio_sk_...with no extra characters. - 403 after adding a scope to an old token. Scopes cannot be edited. Create a new token with the scope.
- 400 on a
GETlist. Onlylimit(1 to 100) andcursorare accepted, each at most once. - 409 on a retry. Check whether the first attempt succeeded. Replays of a successful command with the same key and input return the saved result, not an error.