The StackPath Developer Portal

Integrate our platform directly into your products and dynamically protect your edge.

Get Started    API Reference

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.

Code
Name
Description

1

CANCELLED

The operation was cancelled, typically by the caller.

2

UNKNOWN

Unknown error.

3

INVALID_ARGUMENT

The client specified an invalid argument.

4

DEADLINE_EXCEEDED

The deadline expired before the operation could complete.

5

NOT_FOUND

Some requested entity was not found.

6

ALREADY_EXISTS

The entity that a client attempted to create already exists.

7

PERMISSION_DENIED

The caller does not have permission to execute the specified operation.

8

RESOURCE_EXHAUSTED

Some resource has been exhausted.

9

FAILED_PRECONDITION

The operation was rejected because the system is not in a state required for the operation's execution.

10

ABORTED

The operation was aborted

11

OUT_OF_RANGE

The operation was attempted past the valid range.

12

UNIMPLEMENTED

The operation is not implemented or is not supported/enabled in this service.

13

INTERNAL

Internal errors.

14

UNAVAILABLE

The service is currently unavailable.

15

DATA_LOSS

Unrecoverable data loss or corruption.

16

UNAUTHENTICATED

The request does not have valid authentication credentials for the operation.

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 EdgeCompute workload:

curl --request POST \
  --url https://gateway.stackpath.com/workload/v1/stacks/your_stack_slug/workloads \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer your_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.

Updated about a month ago


Error handling


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.