Errors

Every qibdo Cloud service reports failures in the same canonical shape. This page covers that envelope, the status mapping, and how qibdo error codes are structured.

The error envelope

Errors use the standard google.rpc.Status shape: a numeric gRPC code, a message, and a details array carrying machine-readable ErrorInfo.

{
  "code": 5,
  "message": "[8300002] Bucket not found",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "BUCKET_NOT_FOUND",
      "domain": "com.qibdo.cloud",
      "metadata": {
        "error_code": "8300002",
        "service": "storage",
        "status": "NOT_FOUND",
        "message": "Bucket not found",
        "timestamp": "2026-06-04T12:00:00Z"
      }
    }
  ]
}

• message is prefixed with the qibdo error code in brackets, e.g. [8300002].
• reason is a stable, machine-readable identifier you can branch on (BUCKET_NOT_FOUND).
• metadata.service tells you which service raised it; metadata.error_code is the numeric qibdo code; metadata.status is the canonical status name.
• Unexpected server faults return a generic INTERNAL error with no internal detail; stack traces, SQL, and class names are never exposed.

Status codes

qibdo maps its domain errors to canonical gRPC status codes, which the gateway renders as the matching HTTP status:

Condition	gRPC status	HTTP
Missing or invalid credentials	UNAUTHENTICATED	401
Not allowed to perform the action	PERMISSION_DENIED	403
Resource does not exist	NOT_FOUND	404
Resource already exists	ALREADY_EXISTS	409
Conflicting concurrent change	ABORTED	409
Precondition not met	FAILED_PRECONDITION	400
Invalid argument (default)	INVALID_ARGUMENT	400
Quota or capacity exhausted	RESOURCE_EXHAUSTED	429
Action not supported	UNIMPLEMENTED	501
Upstream/dependency unavailable	UNAVAILABLE	503
Operation timed out	DEADLINE_EXCEEDED	504

Error code structure

Each error also carries a stable, globally-unique numeric code in metadata.error_code, for example 8300002. The wire value is a plain positive integer. Internally qibdo composes that integer from three parts (a service number of one or two digits, a three-digit group, and a three-digit error number) which engineers read as 8_300_002 (service, group, specific error) for legibility in Kotlin. The API always returns the flat integer, never the grouped form. Match on error_code, or on the stable reason; both are stable across releases.

The leading digits identify the service. Earlier services took a single digit; newer services take two, starting with Observability at 10:

Service	Service number	Service	Service number
Vault	2	IAM	6
Compute	3	Taxonomy	7
Topology	4	Storage	8
Network	5	Registry	9
		Observability	10

For example 8300002 is a Storage error and 10300001 is an Observability error. Seven-digit codes that begin with 1 are cross-cutting platform codes that can surface from any service; do not confuse them with Observability’s eight-digit codes, which begin with 10.

Shared codes

A handful of codes come from the shared platform layer rather than a single service. They are seven digits and begin with 1. The 1301xxx validation group can appear on create, update, list, and filter calls for any resource. The 1400xxx engine-routing group appears on calls to engine-based services (paths that carry an engines/{engine} segment).

Code	Reason	Status	Description
1301001	DATA_UNIT_NOT_EXISTS	INVALID_ARGUMENT	The data unit referenced does not exist or is not supported.
1301002	PROPERTY_UPDATE_ON_IMMUTABLE_FIELD	FAILED_PRECONDITION	Cannot update an immutable property.
1301003	UPDATE_MASK_CONTAINS_IMMUTABLE_FIELD	INVALID_ARGUMENT	The update mask contains one or more immutable fields.
1301004	UPDATE_MASK_CONTAINS_UNKNOWN_FIELD	INVALID_ARGUMENT	The update mask contains one or more unknown fields.
1400001	UNKNOWN_ENGINE	INVALID_ARGUMENT	Unknown engine: not one of the service’s supported providers.
1400002	WILDCARD_ENGINE_NOT_ALLOWED	INVALID_ARGUMENT	A concrete engine is required for this operation; the - wildcard is not allowed.
1400003	ENGINE_OPERATION_NOT_SUPPORTED	UNIMPLEMENTED	The engine is not yet supported for this operation.

List and filter requests can also fail with shared validation codes (invalid page token, unsupported filter operator, invalid sort property, and similar), most of which map to INVALID_ARGUMENT (an expired page token is the exception, reported as FAILED_PRECONDITION). See Filtering for the filter and ordering grammar, and Standard responses for the success and pagination shapes.