Skip to content
Soljio Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 as Use only limit and cursor query parameters., Limit must be an integer from 1 to 100., or Provide 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 say Required 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 says The 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:

  1. The header shape. A malformed or missing bearer header returns 401 before anything else.
  2. The path and method: 404, 405.
  3. The body and its headers: 415, 413, and 400, including a bad Idempotency-Key.
  4. The credential and its scopes: 401, 403.
  5. The rate limit: 429.
  6. The operation itself: 400, 404, 409, or 500.

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 GET list. Only limit (1 to 100) and cursor are 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.

Was this page helpful?