Error handling

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:

{
  "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:

{
  "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 that lacks data. See 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. 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.
`401 Unauthorized`	The API token is missing or invalid.	Check your API token.
`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.
`5xx`	An error occurred on our side.	Retry the request later. If the error persists, 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:

{
  "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 explains which actions are possible when.

Request IDs

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

X-Request-ID: 0b9c2e4f-6a1d-4f3e-9c8b-7d6e5f4a3b2c

Contact support

If you need help with a failed request, contact 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.

Remove your API token before you send logs. We never need your token to help you.

Getting started

API basics

API reference

Error response

Validation errors

Processing errors

Status codes

Conflicts

Request IDs

Contact support

​Error response

​Validation errors

​Processing errors

​Status codes

​Conflicts

​Request IDs

​Contact support

Error response

Validation errors

Processing errors

Status codes

Conflicts

Request IDs

Contact support