Errors

The error body

A failed call answers with an HTTP status code and, in most cases, this JSON body:

{
  "error": "Access denied. You do not have permission to perform this action.",
  "code": "FORBIDDEN",
  "module": "apps",
  "correlationId": "3f2b9c1e-6d4a-4e0b-9a51-2c7d8e0f4b6a",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

A field without a value is left out, or sent as null. An error from an older module can lack code and module. Some codes add fields of their own; the code's entry in the reference lists them. Quote the correlationId when you report a problem.

Errors in the problem format

Some routes answer in the standard problem format instead, with the content type application/problem+json. The file routes of apps and container instances and the snapshot routes do, among others:

{
  "type": "…",
  "title": "backups-not-configured",
  "status": 422,
  "detail": "Backups are not enabled on PostgreSQL cluster 'orders', so there is no archive to snapshot into.",
  "code": "backups-not-configured",
  "remediation": "Enable backups in the cluster's Configuration, wait for the first archive, then snapshot.",
  "module": "db-postgres",
  "correlationId": "3f2b9c1e-6d4a-4e0b-9a51-2c7d8e0f4b6a"
}

This body has no error field. The sentence for people is in detail, which some codes leave empty, and title is either a short summary or the code itself. code, module and correlationId mean the same as above.

A client that reads error when it is present, and otherwise detail and then title, finds a sentence to show in every error.

Status codes

Look up a code

A code is documented by the module that owns it. Codes that mean the same whichever module answers are documented once, under the platform's core (kernel), even though the body's module names the module that answered: a file error from an app carries "module": "apps", and its code is on File errors. A module's own codes are on that module's pages.

So look a code up by the pair of module and code first and, when that module does not document the code, by kernel and the code. The platform's documentation service answers GET /docs-hub/errors/{module}/{code} for one exact pair; it does not try kernel for you.

The codes documented under the core are on three pages:

• Error codes — the codes every module can answer with, and the core's own
• File errors — the file routes of apps and container instances
• Snapshot errors — why a snapshot or a restore of a PostgreSQL cluster, SQL Server instance or container instance is refused

Validation errors

Validation failures come in these forms, depending on the route:

• 422 with VALIDATION_FAILED, and one entry per field in details:

  jsonCopy code

  {
    "error": "Validation failed.",
    "code": "VALIDATION_FAILED",
    "details": [{ "field": "Name", "message": "…" }]
  }

  Some checks answer VALIDATION_FAILED with the reason in error and no details.

• 400 with BAD_REQUEST and the field errors in errors: either in the standard problem format, keyed by field, or as a list of messages:

  jsonCopy code

  {
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": { "Region": ["Region is required"] },
    "code": "BAD_REQUEST"
  }

• 400 with BAD_REQUEST and only a message in error.

Permission errors

A 403 usually does not say which permission was missing; the roles that grant an action are listed on each module's permissions page. Ask an owner of the boundary for the role you need.

When the body's code is FORBIDDEN_REQUESTABLE, the permission can be requested as just-in-time access: details names the action, the scope and the role to request. See Request access. With VAULT_GRANT_FORBIDDEN, a request has been filed for you already; see VAULT_GRANT_FORBIDDEN.

Concurrent changes

Apps support optimistic concurrency: reading an app returns an ETag header, and a PATCH that sends it back as If-Match answers 412 if the app has changed since. Without If-Match, a PATCH that loses a race with another change is applied again to the app as it now is, up to five times, so concurrent patches to different fields all land; only when all five attempts lose does it answer 409. Other resources do not use ETag or If-Match; a conflicting change answers 409.

Errors from the gateway

Requests to a module's routes pass the platform's core first, which forwards them to the module. The core answers some errors itself, with "module": "kernel":

• 401 with UNAUTHORIZED and "error": "missing bearer token" — for a missing token, and also for one that is invalid or expired.
• 503 with MODULE_UNAVAILABLE when the module is not running or does not respond. The module it could not reach is in targetModule. See MODULE_UNAVAILABLE.

A module's own 4xx answers are passed on unchanged. A 5xx answer from a module is replaced by {"error": "An internal error occurred.", "code": "…", "module": "…", "correlationId": "…"}, so the detail stays in the platform's logs. The module's code and module are kept, whether the code is in upper or lower case — INTERNAL_ERROR, PLATFORM_ERROR and compute_plan_policy_unavailable alike — as long as they are shaped like a code and a module key; anything else is left out. The replacement body is plain JSON, also when the module answered in the problem format, and has no traceId. The code's documentation says what the error means. A platform that runs in development mode passes 5xx answers on unchanged.

In the CLI

stsh prints the error and exits with a code that tells the failures apart: