API Responses

The following sections provide a guide on the API responses that VikingCloud Portal APIs may return. Product-specific reference documentation should be used as the authoritative source of information on particular APIs.

HTTP Status Codes

As suggested in guides on RESTful APIs, we use both response bodies and HTTP Status codes to convey the status of a request, the related resource, and errors if applicable. In the case of API errors, the status code and body should be used to determine the cause of the error. There are 2 possible classes of errors that may arise, explained below.

Successful Responses (2xx response)

For the most part, successful API responses will return 200, 202, 204 status codes. The following table provides details of when a particular code is provided

HTTP Status Code Description
200 OK The request was successful. The response may include a body with the requested resource or the state of the resource if updated
202 Accepted The request has been accepted for processing, but the processing has not complete. This is useful for asynchronous operations and may return a unique id by which the (state of the) resource may be looked up.
204 No Content A status code and a header are given in the response, but there is no body in the response. This may be returned from operations where the state of the resource is known (Ex. a DELETE call that removes the resource)

See Mozilla's comprehensive list of successful response codes

Client Errors (4xx responses)

Client errors indicate that something was wrong with the client's request. The most common codes that we may return along with reasons can be found in table below

HTTP Status Code Description
400 Bad Request The request parameters (or body) were malformed or invalid. Fix the issues with the request and try again. The response should include errors in the body
401 Unauthorized The token was not provided or was invalid. Reasons that could cause it to be invalid, include:
  • The token has expired
  • The token was signed by the wrong key - this is not the signature that the API expected. Check that you obtained the key for the correct environment (if applicable)
  • The token has been revoked.
In all of these cases, try to obtain a new token and retry your request
403 Forbidden You are not permitted to access the requested resource
404 Not Found The specified resource (or the resource referred to by id) was not found.
405 Method Not Allowed The API was accessed with the wrong method (Ex. HTTP Verb).
409 Conflict The request could not be completed because of a conflict. Ex. unique constraint violation
429 Too Many Requests The API is rate-limited. Wait and try your request again. More details on this can be found in the next section on Rate Limiting

See Mozilla's comprehensive list of client error response codes

Server Errors (5xx responses)

Server errors are less common. Usually, they are caused by transient failures in making requests or unhandled errors. Generally, requests are retryable as-is. Contact support if you receive these errors after retries.

See Mozilla's comprehensive list of server error response codes