Source: https://spooly.eu/en/docs/errors

# Error codes

Errors come with an HTTP status, a fixed code and a German text. Two cases have no code: invalid fields (422) and requests that are too large (413). Program against the code, the text can change.

## Structure

In `detail`, an error with a code carries an object with `code` and `message`. Some carry more details in `data`, here the color the printer reports.

The text in `message` is German, even if you use Spooly in English.

Response (409):

```
{
  "detail": {
    "code": "andere_farbe",
    "message": "Der Drucker meldet in diesem Slot eine andere Farbe als diese Spule. Trotzdem zuordnen?",
    "data": {
      "gemeldet": {
        "farbe": "#E8E9DF",
        "material": "PLA"
      },
      "spule": {
        "farbe": "#1B1B1D"
      }
    }
  }
}
```

Invalid fields in the body or the query come back as 422 with a list in `detail` and no `code`. `loc` names the field, `msg` the reason. This text is English and follows the standard format of the platform. Program against `loc` and `type` here.

Response (422):

```
{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "grams"
      ],
      "msg": "Field required",
      "input": {}
    }
  ]
}
```

Spooly rejects a request over 64 KB before it reads it: 413 with a plain text in `detail`, also without a `code`. [Limits](https://spooly.eu/en/docs/limits)

Response (413):

```
{
  "detail": "Anfrage ist zu groß."
}
```

## All codes

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `invalid_key` | Key missing, unknown or revoked, or the account is not active |
| 403 | `api_disabled` | The API is not enabled for this account |
| 403 | `pro_expired` | Pro has expired. The key stays valid. |
| 403 | `insufficient_scope` | The connection is not allowed to change data |
| 403 | `key_kind` | The key does not fit the address: a spreadsheet key used against the API, another key used against the spreadsheet link, or at the Spoolman address a key that is not of type scale or Klipper printer (and the other way round) |
| 404 | `not_found` | Spool, location, slot, task or printer not found |
| 409 | `slot_autopilot_off` | Slot autopilot is not active, slots can only be read |
| 409 | `andere_farbe` | The printer reports a different color. Repeat with `confirm_color`. |
| 409 | `anderer_chip` | The spool already has a different Bambu chip than the one in the slot. Is it a new roll? |
| 409 | `archiviert` | The spool is archived |
| 409 | `gleichzeitig` | The slot was changed at the same time. Try again. |
| 409 | `tare_missing` | No empty-spool weight is stored for the spool |
| 409 | `spool_in_print` | The spool is in a running print |
| 409 | `place_taken` | Another spool is already on this place |
| 409 | `conflict` | Any other conflict |
| 413 | (no code) | The request is larger than 64 KB |
| 422 | `invalid_input` | Invalid input |
| 422 | `place_invalid` | This place does not exist in the location (see `places`) |
| 422 | `gross_not_above_tare` | The gross weight must be greater than the tare |
| 422 | `above_spool_size` | The weight would be larger than the spool |
| 422 | `invalid_idempotency_key` | The Idempotency-Key must be 1 to 128 visible ASCII characters |
| 422 | `idempotency_conflict` | Something different was already requested with this Idempotency-Key |
| 429 | `fair_use` | Daily limit reached |
| 429 | `too_many_parallel` | Too many simultaneous requests |
| 429 | `change_rate_limit`, `change_daily_limit` and `new_spool_daily_limit` | Change limit reached |
| 429 | `too_many_keys` | Too many new keys in one hour |
| 500 | `internal_error` | That did not work. Try again later. |

## In Home Assistant and with AIs

Home Assistant turns the codes into its own messages. You find them under [troubleshooting](https://spooly.eu/en/docs/home-assistant/troubleshooting). An AI gets the same codes and usually explains them to you itself.