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.

Code	Response	Description
200	Ok	The request was completed successfully. Response body will vary.
201	Created	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.
204	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).

Code	Response	Description
400	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.
401	Unauthorized	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.
403	Forbidden	The API authentication was successful but the user does not have adequate permissions to satisfy the request or the tenant account is locked.
404	Not Found	The resource requested does not exist or was not found.
409	Conflict	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.
5XX	varies	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.

Timeouts

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 Name	Description
X-Green-Stack-Compute-Node	The service node that generated the response
X-Green-Stack-Gateway-Node	The application gateway node that served the response
X-Green-Stack-Realm	For internal troubleshooting and debugging
X-Green-Stack-Request-ID	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 Name	Description
X-Green-Stack-Edge-Cache	Indicates if the response was served from the edge device cache
X-Green-Stack-Edge-Cache-Age	The age of the cached response
X-Green-Stack-Edge-Cache-Control	The Cache-Control header returned by the edge device
X-Green-Stack-Edge-Error	The error message returned by the edge device. Only present if an error has occurred.
X-Green-Stack-Edge-Response	The HTTP status code returned by the edge device
X-Green-Stack-Edge-RTT	The total round-trip-time for the upstream edge request
X-Green-Stack-Edge-Trace	For internal troubleshooting and debugging

Green Stack Error Headers

These headers are included in when an error is returned.

Header Name	Description
X-Green-Stack-Error-Trace	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.

Errors

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