Error codes

Every value the API can return in error.code, and the shape of the response that carries it.

A processor response code isn't an API error code. An error code means the request was refused before or instead of being processed, and the error reference documents it. A processor response code means the request reached a processor and the processor answered, which covers an approval as much as a decline. See the processor response-code reference.

The error reference isn't available right now

This instance couldn't load its API specification, so this page lists nothing. The reference returns as soon as the specification is readable again.

This instance publishes no error reference

The API specification loaded, and it carries no error-code catalog. That's what an instance running a build from before the catalog was published looks like. The error envelope shapes below are accurate whether or not the catalog is present.

Error response shapes

Every failed request returns the same envelope: a single error object. Which of its fields are populated depends on why the request failed, so these are the four shapes a caller has to handle. The bodies are illustrative and carry no real data.

409 Business rule refused the request

The request was understood and rejected by a platform rule. This is the shape that carries a code from the catalog above, so branch on error.code rather than on the message text. The HTTP status is the one listed against the code.

{
  "error": {
    "code": "Transactions:OperationNotAllowed",
    "message": "The operation 'Void' is not allowed on a Sale transaction with result 'Approved' and settlement state 'Settled'.",
    "details": null,
    "data": {
      "correlationId": "0123456789abcdef0123456789abcdef"
    },
    "validationErrors": null
  }
}

400 Request failed validation

One or more fields were rejected before any rule ran. error.code is null on the envelope and the causes are in validationErrors, one entry per failure. An entry carries code when the validator declared a publishable one, and memberPaths when the full path says more than members does (an element inside a collection, for example). Both keys are omitted when they would add nothing.

{
  "error": {
    "code": null,
    "message": "Your request is not valid!",
    "details": "The following errors were detected during validation.",
    "data": {
      "correlationId": "0123456789abcdef0123456789abcdef"
    },
    "validationErrors": [
      {
        "message": "'Amount' must be greater than 0.",
        "members": ["amount"]
      },
      {
        "message": "The card has expired.",
        "members": ["expirationDate"],
        "code": "CardData:CardExpired"
      },
      {
        "message": "'Value' must not be empty.",
        "members": ["value"],
        "memberPaths": ["customFields[2].value"]
      }
    ]
  }
}

404 Resource not found

The id in the path names no record the caller can see. Most resources answer with a null error.code and a message naming the resource type and the id; a resource that publishes a not-found code in the catalog above carries it in error.code instead, so check for one before matching on the message.

{
  "error": {
    "code": null,
    "message": "There is no entity Transaction with id = 7d1f3a52-0c4e-4b8a-9e21-5a6b7c8d9e00!",
    "details": null,
    "data": {
      "correlationId": "0123456789abcdef0123456789abcdef"
    },
    "validationErrors": null
  }
}

403 Caller is not authorized

The credential was accepted and does not carry what the operation requires. The code is the framework's, not a platform code, so it is worth matching on explicitly. Each operation page lists what it requires.

{
  "error": {
    "code": "Volo.Authorization:010001",
    "message": "Authorization failed! Given policy has not granted.",
    "details": null,
    "data": {
      "correlationId": "0123456789abcdef0123456789abcdef"
    },
    "validationErrors": null
  }
}

500 Unexpected server fault

Something failed that no rule anticipated. There is no code to branch on and the message is deliberately generic: the diagnostic detail stays in the platform's logs rather than going to the caller. Quote error.data.correlationId (the same value as the X-Correlation-Id response header) when you contact support: it's what finds the failure in those logs. Retrying an unsafe operation after this risks a duplicate, so reconcile before you retry.

{
  "error": {
    "code": null,
    "message": "An internal error occurred during your request!",
    "details": null,
    "data": {
      "correlationId": "0123456789abcdef0123456789abcdef"
    },
    "validationErrors": null
  }
}

Codes by module

error.code carries one of these values, so a caller can branch on the cause without parsing message text. The status column is what this instance returns when the code is raised. A code with no message defined is listed rather than hidden: it still reaches a caller over the wire.