Errors

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) and the 403 for plain-HTTP requests (Network); handle them by status (and Retry-After for 429).

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

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

{
  "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
`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. 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 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.

Get started

Authentication and security

API conventions

Webhooks

Provider 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