> ## Documentation Index
> Fetch the complete documentation index at: https://docs-consumer.voucher.allride.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error format, status codes, validation errors and which errors to retry.

When a request fails, the API answers with a `4xx` or `5xx` status and a JSON body that names a stable, machine-readable `errorCode`. Branch on `errorCode`, not on the message text. Every code is listed with its meaning and the fix in the [error catalog](https://docs-consumer.voucher.allride.io/errors/catalog.md).

## Error format

Error responses have `Content-Type: application/json` and this body:

```json theme={null}
{
  "errors": [
    {
      "message": "Data failed validation",
      "statusCode": 400,
      "errorCode": "data-failed-validation",
      "more": {
        "validationErrors": [
          {
            "property": "items[1].quantity",
            "constraint": "too-large",
            "message": { "en": "Must be at most 10.", "de": "Darf höchstens 10 sein." }
          }
        ]
      }
    }
  ]
}
```

| Member | Always | Meaning |
| - | - | - |
| `errors` | yes | Array of errors. In v1 it holds exactly one entry |
| `errors[0].message` | yes | Human-readable explanation. Do not parse it; it can change |
| `errors[0].statusCode` | yes | The HTTP status |
| `errors[0].errorCode` | yes | Stable kebab-case code, the value your code branches on |
| `errors[0].more` | for some codes | Details for the code, for example `requiredPermissions` on `missing-permission` or `validationErrors` on `data-failed-validation`. The catalog lists the members per code |
| `errors[0].requestId` | `5xx` only | The request id, also sent as the `X-Request-Id` header |

Server errors never contain internal details. Their message is always the same:

```json theme={null}
{
  "errors": [
    {
      "message": "Something went wrong on our side",
      "statusCode": 500,
      "errorCode": "internal-error",
      "requestId": "0c9f2ea5-fe09-463c-8f96-b6cae67800ad"
    }
  ]
}
```

Ignore members you do not know, inside the entry and inside `more`: new codes and new detail members can be added within v1. A resource of another partner is always answered as if it did not exist (`404`), never with `403`.

## Status codes

| Status | Meaning | Typical codes |
| - | - | - |
| `400` | The request is malformed or invalid | [`data-failed-validation`](https://docs-consumer.voucher.allride.io/errors/catalog#data-failed-validation), [`malformed-json`](https://docs-consumer.voucher.allride.io/errors/catalog#malformed-json), [`invalid-header`](https://docs-consumer.voucher.allride.io/errors/catalog#invalid-header), [`invalid-idempotency-key`](https://docs-consumer.voucher.allride.io/errors/catalog#invalid-idempotency-key) |
| `401` | No valid credential | [`unauthenticated`](https://docs-consumer.voucher.allride.io/errors/catalog#unauthenticated), [`api-key-invalid`](https://docs-consumer.voucher.allride.io/errors/catalog#api-key-invalid) |
| `403` | An access gate refused the request | [`missing-permission`](https://docs-consumer.voucher.allride.io/errors/catalog#missing-permission), [`api-access-inactive`](https://docs-consumer.voucher.allride.io/errors/catalog#api-access-inactive), [`ip-not-allowed`](https://docs-consumer.voucher.allride.io/errors/catalog#ip-not-allowed), [`partner-suspended`](https://docs-consumer.voucher.allride.io/errors/catalog#partner-suspended), [`partner-role-missing`](https://docs-consumer.voucher.allride.io/errors/catalog#partner-role-missing) |
| `404` | Unknown resource, a resource of another partner, or an unknown path | `<resource>-not-found` such as [`voucher-set-not-found`](https://docs-consumer.voucher.allride.io/errors/catalog#voucher-set-not-found); [`route-not-found`](https://docs-consumer.voucher.allride.io/errors/catalog#route-not-found) |
| `405` | The path exists, the method does not; see the `Allow` header | [`method-not-allowed`](https://docs-consumer.voucher.allride.io/errors/catalog#method-not-allowed) |
| `409` | Conflict with the current state | [`voucher-set-depleted`](https://docs-consumer.voucher.allride.io/errors/catalog#voucher-set-depleted), [`price-acceptance-required`](https://docs-consumer.voucher.allride.io/errors/catalog#price-acceptance-required), [`idempotency-key-in-use`](https://docs-consumer.voucher.allride.io/errors/catalog#idempotency-key-in-use), [`concurrent-update`](https://docs-consumer.voucher.allride.io/errors/catalog#concurrent-update) |
| `410` | Gone: expired or past its sunset | [`api-version-sunset`](https://docs-consumer.voucher.allride.io/errors/catalog#api-version-sunset), [`webhook-event-expired`](https://docs-consumer.voucher.allride.io/errors/catalog#webhook-event-expired) |
| `422` | Well-formed, but a business rule refuses it | [`idempotency-key-reused`](https://docs-consumer.voucher.allride.io/errors/catalog#idempotency-key-reused), [`batch-too-large`](https://docs-consumer.voucher.allride.io/errors/catalog#batch-too-large), [`void-window-expired`](https://docs-consumer.voucher.allride.io/errors/catalog#void-window-expired) |
| `429` | Too many requests from your IP address: the network edge allows up to 30,000 authenticated requests per 60 seconds (1,200 for the keyless `/public/` and `/auth/` endpoints) and then blocks the address for 60 seconds; wait for `Retry-After` ([Edge limits](https://docs-consumer.voucher.allride.io/guides/limits.md#edge-limits)) | none: the edge answers, so the body is not this error format |
| `500` | Unexpected failure | [`internal-error`](https://docs-consumer.voucher.allride.io/errors/catalog#internal-error) |
| `502` | A service the platform depends on failed | [`upstream-error`](https://docs-consumer.voucher.allride.io/errors/catalog#upstream-error), [`upstream-unavailable`](https://docs-consumer.voucher.allride.io/errors/catalog#upstream-unavailable) |
| `503` | Temporarily overloaded or unavailable; see `Retry-After` | [`service-unavailable`](https://docs-consumer.voucher.allride.io/errors/catalog#service-unavailable), [`db-unavailable`](https://docs-consumer.voucher.allride.io/errors/catalog#db-unavailable), [`query-timeout`](https://docs-consumer.voucher.allride.io/errors/catalog#query-timeout) |
| `504` | A dependency did not answer in time | [`upstream-timeout`](https://docs-consumer.voucher.allride.io/errors/catalog#upstream-timeout) |

`401` responses carry a `WWW-Authenticate` header. Each operation's reference page lists the codes it can return in addition to the common ones.

## Validation errors

A body, query parameter, path parameter or header that does not pass validation is answered with `400` [`data-failed-validation`](https://docs-consumer.voucher.allride.io/errors/catalog#data-failed-validation). All problems are collected in one pass and listed in `more.validationErrors`:

| Member | Meaning |
| - | - |
| `property` | Where the problem is: a path into your body (`voucherSetId`, `redemptionEntity.refId`, `items[2].quantity`) or the name of the query parameter, path parameter or header (`perPage`, `redemptionId`, `Idempotency-Key`) |
| `constraint` | The rule that failed, as a kebab-case item code: `required`, `unknown-field`, `unknown-parameter`, `invalid-id`, `invalid-timestamp`, `too-long`, `mutually-exclusive`, … The codes are listed under [Validation item codes](https://docs-consumer.voucher.allride.io/errors/catalog.md#validation-item-codes) |
| `message` | The explanation in English (`en`) and German (`de`) |
| `params` | Parameters of the rule, when it has some: `min` and `max` for `invalid-page`, `allowed` for `invalid-sort` |
| `value` | The rejected value, when it is safe to return |

Typical causes:

* a required property is missing (`required`) or `null` where it must not be (`null-not-allowed`);
* a property or query parameter the operation does not define (`unknown-field`, `unknown-parameter`): the API is strict, so typos never pass silently;
* an id that is not a positive integer (`invalid-id`);
* a timestamp without an offset (`invalid-timestamp`);
* a list parameter outside its rules: `page` or `perPage` out of range (`invalid-page`), a `sort` field that is not allowed (`invalid-sort`), or an unsupported filter field, operator or value (`invalid-filter`); see [Pagination](https://docs-consumer.voucher.allride.io/guides/pagination.md#invalid-list-parameters);
* both `voucherSetId` and `providerId` in a redemption (`mutually-exclusive`).

Batch operations and content checks use the same list for item failures: `property` names the item (`items[2]`) and `constraint` the reason.

## Retrying safely

Combine retries with [idempotency keys](https://docs-consumer.voucher.allride.io/guides/idempotency.md): a key makes a `POST` safe to send again.

| Response | Retry? | How |
| - | - | - |
| Network error or timeout | yes | Same `Idempotency-Key`, exponential backoff with jitter |
| `409 idempotency-key-in-use` | yes | Same key, after `Retry-After` (1 second) |
| `409 concurrent-update` | yes | Same key, with backoff: these outcomes are not stored |
| `429` from the network edge | yes | Same key, after `Retry-After`; slow down (one request at a time for large downloads) |
| `500`, `502`, `503`, `504` | yes | Same key, after `Retry-After` when present, else exponential backoff |
| Any other `4xx` | no | Change the request first; then use a **new** key, because a stored `4xx` is final for its key |

Never retry `401` or `403` in a loop: they need a configuration change (a valid key, a permission, an allowlist entry or an active partner).

## Getting help

If you cannot resolve an error:

1. Look up the `errorCode` in the [error catalog](https://docs-consumer.voucher.allride.io/errors/catalog.md) and follow "What to do".
2. Check the operation's reference page for the codes and rules it documents.
3. Contact your AllRide account manager, or AllRide through the **Support** link at the top of this site, with the `X-Request-Id` response header (for `5xx` also in `requestId`), the time of the request, the operation and the `errorCode`. Do not send API keys, webhook secrets or issued voucher codes.

## Related

* [Error catalog](https://docs-consumer.voucher.allride.io/errors/catalog.md)
* [Idempotency](https://docs-consumer.voucher.allride.io/guides/idempotency.md)
* [Requests and responses](https://docs-consumer.voucher.allride.io/guides/requests-and-responses.md)
* [Authentication](https://docs-consumer.voucher.allride.io/guides/authentication.md)


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