---
title: Errors
description: 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:

```json
{
  "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](/developers/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](/developers/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](/developers/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](/developers/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.
