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.
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).
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.
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.
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.
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 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.
Last updated
