Responses and Errors

Status Codes

Every request will return an HTTP status code that indicates the success or failure of the operation. For more information about response codes, see the MDN HTTP response status code documentation.

Success Codes

In general: Codes in the 2xx range indicate success.




The request was completed successfully. Response body will vary.



In response to a PUT or POST request, the resource was created successfully. The new resource's ID will be returned in the response body.


No Content

The request was completed successfully and there is no response body to return. Such as when an object has been deleted. The response body will be null.

Error Response Codes

Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a resource could not be found, etc.). Codes in the 5xx range indicate an error with the Green Stack backend (these are rare).



Bad Request

The request was malformed, provided incorrect/incomplete/conflicting parameters, or the requested endpoint does not exist. The response body will contain additional information about why the error has occurred. Do not repeat the request without modifying it first.



The request requires an Authorization header and a valid token but either neither was provided or the provided token has expired. Refer to the error message provided to determine the proper course of action.



The API authentication was successful but the user does not have adequate permissions to satisfy the request or the tenant account is locked.


Not Found

The resource requested does not exist or was not found.



The provided combination of parameters results in a conflict and the resource cannot be updated. The error message output will provide additional information as to why the call cannot be completed.



The API encountered an internal error when processing the request. The error message provided may provide additional information. Retrying the request after a few minutes may be successful.


If Green Stack takes more than 10 seconds to process an API request, Green Stack will terminate the request and you will receive an error. Counterbalance reserves the right to change the timeout window to protect the speed and reliability of the API.

Response Headers

Every response will include headers that give more details about the response and status. Headers that start with X- or x- are custom to Green Stack.

Standard HTTP Headers

These headers are standard HTTP headers that the client can use to evaluate the response.

Green Stack Headers

These headers are included in all responses.

Header NameDescription


The service node that generated the response


The application gateway node that served the response


For internal troubleshooting and debugging


The application gateway request ID

Green Stack Edge Headers

These headers are returned when the API operation involves a request to an edge device.

Header NameDescription


Indicates if the response was served from the edge device cache


The age of the cached response


The Cache-Control header returned by the edge device


The error message returned by the edge device. Only present if an error has occurred.


The HTTP status code returned by the edge device


The total round-trip-time for the upstream edge request


For internal troubleshooting and debugging

Green Stack Error Headers

These headers are included in when an error is returned.

Header NameDescription


The error tracing hash for internal debugging. Counterbalance Support may request this value during a technical support request.

Response Body

Many operations will return a response body. Unless otherwise specified, the response body is in JSON format. Responses will include a Content-Type header that indicates the type of data returned in the response.

Summary Representation

When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the "summary" representation of the resource. Some attributes are computationally expensive for the API to provide. For performance reasons, the summary representation excludes those attributes. To obtain those attributes, fetch the "detailed" representation.

Detailed representations

When you fetch an individual resource, the response typically includes all attributes for that resource. This is the "detailed" representation of the resource. Note that authorization sometimes influences the amount of detail included in the representation.


Error responses will vary depending on the situation. In general, a brief description of the error will be provided with suggested next steps.

    "error": {
    "trace": "034dd6ad00770337bb07e906d919ed50f8884e86"

Error Tracing

Most errors are automatically logged and reported. These errors will return a trace ID in the error response body. Counterbalance Support may request this trace ID value to assist with troubleshooting or debugging the API.

This trace ID is also added as a header in the response.

X-Green-Stack-Error-Trace: 034dd6ad00770337bb07e906d919ed50f8884e86

Last updated


©2019 - 2024 Counterbalance Software LLC