Response codes and errors

The Opaque API uses standard HTTP response codes to indicate the outcome of an API request. These codes are categorized as follows:

2xx: Successful request
4xx: Client-side issue (e.g., invalid parameters, authentication failure)
5xx: Server-side issue (e.g., API or management hub issues).

The following sections provide details on status codes, common errors, and response structure. For endpoint-specific response details, see the API reference.

HTTP status codes

Code	Title	Description
200	OK	The request was successful.
204	No Content	The request was successful, but no content is returned.
400	Bad Request	A generic client error. The response body provides error details.
400	Opaque Error	The request does not meet Opaque's requirements. See response details.
400	Management plane error	The requested resource (e.g., UUID) does not exist.
401	Unauthorized	Authentication credentials are missing or invalid.
403	Forbidden	The user does not have permission to access this resource or operation.
404	Not found	The requested resource path is incorrect.
405	Method Not Allowed	The HTTP method is not supported for this endpoint.
500	Internal server error	An unexpected error occurred while connecting to the management plane.
500	Unknown Error	A generic server-side error. The response body provides additional details.

Error responses

The API returns errors as JSON objects containing structured information about what went wrong. Each error includes the following fields.

Field	Type	Description
detail	string	A detailed explanation of the error.
status	integer	The corresponding HTTP status code.
title	string	A short, human-readable summary of the error.
type	string	The type or category of error (e.g., exception).

Common error examples

The following are common API errors, categorized by type, along with example responses.

Authentication errors

These occur when authentication credentials are missing or invalid.

Example: 401 Unauthorized

{
  "detail": "No authorization token provided",
  "status": 401,
  "title": "Unauthorized",
  "type": "about:blank"
}

Invalid parameters

These errors result from incorrect or missing request parameters.

Example: 400 Bad Request (Resource Not Found)

{
  "detail": "failed to get cluster: ent: cluster not found",
  "status": 400,
  "title": "Management plane error",
  "type": "exception"
}

If the the UUID in the request path is incorrectly formatted, the request may fail with a server error.

Example: 500 Unknow Error (malformed UUID)

{
  "detail": "badly formed hexadecimal UUID string",
  "status": 500,
  "title": "Unknown Error",
  "type": "exception"
}

Request body errors

These occur when the request body contains invalid JSON or is missing required fields.

Example: 400 Bad Request (invalid JSON)

{
 "detail": "Request body is not valid JSON",
 "status": 400,
 "title": "Bad Request",
 "type": "about:blank"
}