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 Codesmessage
: A general error messagedetails
: 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 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'smessage
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 1 month ago