> ## Documentation Index
> Fetch the complete documentation index at: https://developers.simplesell.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> HTTP status codes and error responses of the SimpleSell API.

The SimpleSell API uses HTTP status codes to indicate whether a request succeeded. Codes in the `2xx` range mean success. Codes in the `4xx` range mean the request failed, for example because of invalid data or a missing API token. Codes in the `5xx` range mean something went wrong on our side.

## Error response

Error responses contain a `message` that describes the error:

```json theme={null}
{
  "message": "Parcel not found."
}
```

Use the status code to handle errors in your code. The `message` is intended for logging and debugging. Its wording can change.

## Validation errors

If the request data is invalid, the API responds with `422 Unprocessable Entity`. The `errors` object lists the messages for each invalid field:

```json theme={null}
{
  "message": "The receiver.country field must be a valid country code.",
  "errors": {
    "receiver.country": [
      "The receiver.country field must be a valid country code."
    ]
  }
}
```

Fields in nested objects and arrays use dot notation, such as `receiver.country` or `items.0.quantity`.

The API also returns validation errors when you [process a parcel](/api/v1/parcels/process-a-parcel) that lacks data. See [Checks before processing](/api/v1/how-parcels-work#checks-before-processing).

## Processing errors

Errors from your carrier don't return an HTTP error, because processing runs in the background. They appear in the parcel's `processing_errors` once processing has completed. See the [Quickstart](/api/v1/quickstart).

Processing errors contain the messages your carrier returns, so their language and wording depend on the carrier. Show them to the person who can fix the parcel data, but don't parse them in your code.

## Status codes

| Status | Meaning | What to do |
| - | - | - |
| `200 OK` | The request succeeded. | |
| `201 Created` | The resource was created. | |
| `202 Accepted` | The request was accepted and runs in the background. | Check the status at the URL in the `Location` header. |
| `204 No Content` | The request succeeded and has no response body. | |
| `400 Bad Request` | A query parameter is invalid, for example an unknown sort field or a filter timestamp in the wrong format. | Check the query parameters against the [API reference](/api/v1/parcels/list-parcels). |
| `401 Unauthorized` | The API token is missing or invalid. | Check your [API token](/api/v1/authentication). |
| `402 Payment Required` | Your plan doesn't include API access, for example the **Free** plan. | Upgrade to the **Essential** plan or higher. |
| `404 Not Found` | The resource doesn't exist, or the requested document doesn't exist. | Check the ID in the URL. |
| `409 Conflict` | The request isn't possible at this point, for example because the parcel is already processed. | Check the `message` and retrieve the resource. |
| `422 Unprocessable Entity` | The request data contains validation errors. | Fix the fields listed in `errors`. |
| `429 Too Many Requests` | You exceeded your rate limit. | Wait for the number of seconds in the `Retry-After` header. See [Rate limits](/api/v1/rate-limits). |
| `5xx` | An error occurred on our side. | Retry the request later. If the error persists, [contact support](#contact-support). |

## Conflicts

A `409 Conflict` means the request is valid, but isn't possible at this point in the resource's lifecycle. For example, you can't update a parcel that is already processed:

```json theme={null}
{
  "message": "Parcel is not editable."
}
```

Don't retry the request unchanged. The `message` explains what prevented the request. Retrieve the resource to check where it is in its lifecycle.

For parcels, the [parcel lifecycle](/api/v1/how-parcels-work#parcel-lifecycle) explains which actions are possible when.

## Request IDs

Every response contains an `X-Request-ID` header with a unique ID for the request:

```http theme={null}
X-Request-ID: 0b9c2e4f-6a1d-4f3e-9c8b-7d6e5f4a3b2c
```

## Contact support

If you need help with a failed request, contact [support@simplesell.de](mailto:support@simplesell.de) and include:

* The request ID from the `X-Request-ID` header
* The request: method, URL, and body
* The response: status code and body

This helps us find the request in our logs and reproduce the problem.

<Warning>
  Remove your API token before you send logs. We never need your token to help you.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.