Errors

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.

Error format

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

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

{
  "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`, `malformed-json`, `invalid-header`, `invalid-idempotency-key`
`401`	No valid credential	`unauthenticated`, `api-key-invalid`
`403`	An access gate refused the request	`missing-permission`, `api-access-inactive`, `ip-not-allowed`, `partner-suspended`, `partner-role-missing`
`404`	Unknown resource, a resource of another partner, or an unknown path	`<resource>-not-found` such as `voucher-set-not-found`; `route-not-found`
`405`	The path exists, the method does not; see the `Allow` header	`method-not-allowed`
`409`	Conflict with the current state	`voucher-set-depleted`, `price-acceptance-required`, `idempotency-key-in-use`, `concurrent-update`
`410`	Gone: expired or past its sunset	`api-version-sunset`, `webhook-event-expired`
`422`	Well-formed, but a business rule refuses it	`idempotency-key-reused`, `batch-too-large`, `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)	none: the edge answers, so the body is not this error format
`500`	Unexpected failure	`internal-error`
`502`	A service the platform depends on failed	`upstream-error`, `upstream-unavailable`
`503`	Temporarily overloaded or unavailable; see `Retry-After`	`service-unavailable`, `db-unavailable`, `query-timeout`
`504`	A dependency did not answer in time	`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. 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
`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;
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: 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:

Look up the errorCode in the error catalog and follow “What to do”.
Check the operation’s reference page for the codes and rules it documents.
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.

Get started

Authentication and security

API conventions

Webhooks

Consumer guides

Workspace

Error format

Status codes

Validation errors

Retrying safely

Getting help

​Error format

​Status codes

​Validation errors

​Retrying safely

​Getting help

​Related

Error format

Status codes

Validation errors

Retrying safely

Getting help

Related