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

# Errors

> The error format, status codes and how to retry.

## Error format

Every 4xx and 5xx response from the API has `Content-Type: application/json` and this body. Two responses come from the network edge instead and carry no such body: 429 (rate limit, see [Limits → Edge limits](https://docs-provider.voucher.allride.io/guides/limits.md#edge-limits)) and the 403 for plain-HTTP requests ([Network](https://docs-provider.voucher.allride.io/guides/network.md)); handle them by status (and `Retry-After` for 429).

```json theme={null}
{
  "errors": [
    {
      "message": "No voucher set with this id exists for your partner.",
      "statusCode": 404,
      "errorCode": "voucher-set-not-found"
    }
  ]
}
```

| Member | Always | Meaning |
| - | - | - |
| `errors` | yes | Array of errors. In v1 it holds exactly one entry |
| `errors[0].errorCode` | yes | Stable kebab-case code. **Branch on this.** Every code is in the [error catalog](https://docs-provider.voucher.allride.io/errors/catalog.md) |
| `errors[0].statusCode` | yes | The HTTP status |
| `errors[0].message` | yes | Human-readable explanation in English for people and logs. Do not parse it; it can change. Validation items carry their own `message` in English and German |
| `errors[0].more` | for some codes | Details for the code, for example `validationErrors` (`data-failed-validation`), `requiredPermissions` (`missing-permission`), `requiredRole` (`partner-role-missing`), `openChangeRequestId` (`change-request-open`) or `references` (`brand-asset-in-use`). The catalog lists the members per code |
| `errors[0].requestId` | `5xx` only | The request id to quote to support, also sent as the `X-Request-Id` header of every response |

Ignore members you do not know, inside the entry and inside `more`: new codes and new detail members can be added within v1.

A server error looks like this:

```json theme={null}
{
  "errors": [
    {
      "message": "Something went wrong on our side",
      "statusCode": 500,
      "errorCode": "internal-error",
      "requestId": "0b6f3c1e-9d5a-4c43-a2a8-1f3d2b7c9e10"
    }
  ]
}
```

## Status codes

| Status | Meaning |
| - | - |
| 400 | The request is malformed or invalid: `data-failed-validation`, `malformed-json`, `invalid-header`, `invalid-idempotency-key` |
| 401 | No valid credential: `unauthenticated`, `token-invalid`, `api-key-invalid`; for dashboard users also `token-expired` and `session-revoked` (sign in again) |
| 403 | Authenticated but not allowed: `missing-permission`, `api-access-inactive`, `ip-not-allowed`, `partner-role-missing`, … |
| 404 | The path or the resource does not exist **for your partner**. Another partner's resource is always 404, never 403. |
| 405 | The path exists, but not with this method; see the `Allow` header |
| 409 | Conflict with the current state: `invalid-state-transition`, `change-request-open`, `voucher-set-archived`, `idempotency-key-in-use`, … |
| 410 | Gone: `api-version-sunset`, `webhook-event-expired` |
| 422 | Valid input that breaks a business rule: `invalid-schedule`, `batch-too-large`, `link-host-in-use`, `content-blocked`, `idempotency-key-reused`, … |
| 429 | Too many requests from your IP at the edge; not an API error body. Wait for `Retry-After` ([Edge limits](https://docs-provider.voucher.allride.io/guides/limits.md#edge-limits)) |
| 500 | `internal-error` |
| 502, 504 | An upstream service failed or timed out (single sign-on setup only) |
| 503 | `service-unavailable`, `db-unavailable`, `query-timeout`; see `Retry-After` |

## Validation errors

Invalid properties, query parameters, path parameters or headers give **400 `data-failed-validation`**. All problems are collected in one pass and listed in `more.validationErrors`:

```json theme={null}
{
  "errors": [
    {
      "message": "Data failed validation",
      "statusCode": 400,
      "errorCode": "data-failed-validation",
      "more": {
        "validationErrors": [
          {
            "property": "internalName",
            "constraint": "too-long",
            "params": { "max": 120 },
            "message": { "en": "Must be at most 120 characters.", "de": "Darf höchstens 120 Zeichen lang sein." }
          },
          {
            "property": "content.linkTemplate",
            "constraint": "invalid-link-template",
            "message": { "en": "Placeholders are allowed only in the path, query or fragment.", "de": "Platzhalter sind nur im Pfad, in der Query oder im Fragment erlaubt." }
          }
        ]
      }
    }
  ]
}
```

| Member | Meaning |
| - | - |
| `property` | Where the problem is: a path into your body (`content.name.de`, `vouchers[17].value`) or the name of the query parameter, path parameter or header (`perPage`, `filter[status]`, `X-Request-Id`) |
| `constraint` | The rule that failed, as a kebab-case item code: `required`, `unknown-field`, `unknown-parameter`, `too-long`, `invalid-enum-value`, `invalid-id`, `invalid-timestamp`, `invalid-i18n-text`, … All are listed under [Validation item codes](https://docs-provider.voucher.allride.io/errors/catalog.md#validation-item-codes) |
| `message` | The explanation in English (`en`) and German (`de`) |
| `params` | The rule's parameters, for example `{"max": 120}` for `too-long`; left out when the rule has none |
| `value` | The rejected value, echoed only when it is a number or boolean. Strings are never returned, so secrets, voucher values and personal data never come back in an error |

List parameters use the same response: `page` or `perPage` out of range (`invalid-page`), a `sort` field that is not allowed (`invalid-sort`), an unsupported filter field, operator or value (`invalid-filter`) or an undeclared parameter (`unknown-parameter`); see [Pagination](https://docs-provider.voucher.allride.io/guides/pagination.md#invalid-list-parameters).

In a batch, one invalid item fails the whole request and nothing is written; `property` names the item (`vouchers[17].value`).

## Retrying safely

| Outcome | Retry? |
| - | - |
| Network error, timeout, 500, 502, 503, 504 | Yes, with the **same** `Idempotency-Key`, backoff and `Retry-After` |
| 409 `idempotency-key-in-use` | Yes, same key, after `Retry-After` |
| 409 `concurrent-update` | Yes, same key, with backoff |
| 429 | Yes, after `Retry-After` |
| 409 `invalid-state-transition` and other state conflicts | Not as is: the resource changed. Read it again, decide whether the command still applies, and send it with a **new** key |
| Any other 4xx | No. Change the request first, and use a **new** key: a stored 4xx is final for its key |

See [Idempotency](https://docs-provider.voucher.allride.io/guides/idempotency.md#retry-strategy) for a client sketch.

## Getting help

Contact your AllRide account manager, or AllRide API support through the **Support** link in the top navigation, with the `errorCode`, the `X-Request-Id` (or `requestId` of a 5xx), the operation, the time (UTC) and the environment. Never send API keys, webhook secrets or voucher values.

## Related

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


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