Errors

#The shape of an error

Every error is application/problem+json (RFC 9457):

{
  "type": "https://api.pantechdynamics.com/problems/insufficient-credit",
  "title": "Insufficient credit",
  "status": 402,
  "code": "INSUFFICIENT_CREDIT",
  "detail": "This instance needs NGN 15,040.00 of credit upfront and NGN 2,000.00 is available. Top up your credit or add a card, then try again.",
  "request_id": "req_6Yq8mB2x0dKpL4vS"
}

• code is the stable, machine-readable reason. Branch on it. It never changes within v1.
• detail explains this occurrence for a person. Show it, log it, but do not parse it, because its wording can change.
• request_id identifies the request. Quote it to support.

request_id is also in every response's X-Request-Id header, errors or not, so log it with each call you make.

A validation error lists every bad field in errors, so you can fix them all at once:

{
  "status": 422,
  "code": "VALIDATION_FAILED",
  "title": "Validation failed",
  "detail": "plan_slug: must identify an active plan.",
  "request_id": "req_6Yq8mB2x0dKpL4vS",
  "errors": [
    { "field": "plan_slug", "code": "PLAN_NOT_FOUND", "message": "must identify an active plan" }
  ]
}

Its detail names each bad field and what it must be (field: message, separated by ;), so it is useful on its own. Show each entry of errors beside its field, and branch on its code.

#By status

#Request and authentication codes

#Account and billing codes

#Resource state codes

These mean the request was fine but the resource cannot do it now.

#Database codes

The database endpoints have codes of their own, with a page that explains each one: database error codes. In short:

#Kubernetes codes

The managed Kubernetes endpoints have codes of their own; the guide's troubleshooting explains each, field codes included. In short:

#Private network codes

From adding a private database network interface to a standard instance:

#Field codes

These appear inside errors on a 422, each with the field it is about.

#When an operation fails

An accepted change (202) can still fail later. Its operation then ends failed, and its failure says why:

{
  "id": "op_…",
  "kind": "attach_private_network",
  "status": "failed",
  "failure": {
    "code": "SECURITY_GROUP_ALLOWS_PRIVATE_NETWORK",
    "reason": "The instance's security group was changed to allow 10.250.0.0/20 before the interface was added. Narrow it, then try again."
  }
}

Branch on failure.code, such as DATABASE_STORAGE_GROW_FAILED or INSTANCE_PRIVATE_NETWORK_ATTACH_FAILED; show failure.reason, whose wording can change. The resource is left as it was before. These are listed with the guide for each feature, for example the database error codes. Retry a failed operation with a new Idempotency-Key: the old one replays the failure.

A change the platform itself could not carry out (creating, starting or resizing a machine, for example) fails with one of these codes, whatever the resource:

New codes may be added within v1. Treat an unknown code by its status.