Error handling

Errors from the StackPath API conform to the HTTP specification for error responses. Clients should inspect their responses' status codes to determine if a response was an error or not:

• Status codes 200 - 299 denote a successful response.
• Status codes 400 - 499 are errors caused by the requesting client.
• Status codes 500 - 599 are errors caused by the StackPath backend.

Error Structure

Note this typical 404 Not Found error response. It has an HTTP status code and a response body with more information:

HTTP/1.1 404 Not Found
Date: Wed, 04 Mar 2020 23:28:32 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15724800; includeSubDomains

{
  "code": 5,
  "message": "no stack found for provided id",
  "details": [
    {
      "@type": "type.stackpathapis.com/stackpath.rpc.RequestInfo",
      "requestId": "49f487a4561e045c",
      "servingData": ""
    }
  ]
}

All error response bodies contain three properties:

• code: A numeric error code. For more information about error codes, see Codes
• message: A general error message
• details: An array containing further details about the error. For more information about error details, see Details

Codes

All errors return a code number. This code reflects the underlying error number produced within StackPath's backend systems. These codes and the error response's HTTP status code help categorize the kind of error that occurred.

📘

StackPath employs a gRPC-based micro-service architecture on the back end. These codes are gRPC status codes and are described in further detail at Status codes and their use in gRPC in the gRPC project.

Details

StackPath API errors contain an array of details about the error that can help troubleshoot the error. Error details are JSON objects of varying structure, though all error details have a @type property that describes the structure. Given the following request to create a new Edge Compute workload:

$ curl --request POST \
  --url https://gateway.stackpath.com/workload/v1/stacks/STACK_ID/workloads \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer BEARER_TOKEN' \
  --data '{
    "workload": {
      "name": "My Compute Workload",
      "slug": "my-compute-workload",
      "metadata": {
        "version": "1"
      },
      "spec": {
        "containers": {
          "app": {
            "image": "nginx:latest"
          }
        }
      }
    }
  }'

This request has a few missing required properties, the app container's resources and the workload's targets. Trying to create this workload produces an error:

HTTP/1.1 400 Bad Request
Date: Thu, 05 Mar 2020 21:42:58 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Strict-Transport-Security: max-age=15724800; includeSubDomains

{
  "code": 3,
  "message": "Invalid workload specification",
  "details": [
    {
      "@type": "type.stackpathapis.com/stackpath.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "workload.spec.containers[app].resources",
          "description": "Required value"
        },
        {
          "field": "workload.targets",
          "description": "Required value"
        }
      ]
    },
    {
      "@type": "type.stackpathapis.com/stackpath.rpc.RequestInfo",
      "requestId": "690b23c940c67db0",
      "servingData": ""
    }
  ]
}

This response's details array contains two items, reasons why the request was invalid and general information about the request that produced the error. The type.stackpathapis.com/stackpath.rpc.BadRequest detail describes the fields missing from the request.

🚧

Some 400 Bad Request errors do not contain a type.stackpathapis.com/stackpath.rpc.BadRequest detail. In that case, check the error's message for more details about missing or incorrect fields.

Reporting Errors to StackPath

An error's type.stackpathapis.com/stackpath.rpc.RequestInfo detail contains information about the request. If you need to contact StackPath's support team about an API error then reference the error's requestId. StackPath's support team and engineers can search internal logs to find more information about what generated the error.