Errors and request IDs

Handle stable Bukki API errors and retain request IDs for support.

Errors use a consistent JSON envelope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The API key does not have the required scope."
  },
  "requestId": "req_..."
}

Common status codes

HTTP status	Error code	Meaning
400	VALIDATION_ERROR	A parameter is invalid
401	UNAUTHORIZED	The API key is missing, invalid, revoked, or expired
403	FORBIDDEN	The key lacks a scope or the workspace is not eligible
429	RATE_LIMITED	A key or workspace exceeded its request allowance
503	SERVICE_UNAVAILABLE	A required API dependency is temporarily unavailable

Retain requestId in your structured logs and include it in support requests. Never send the corresponding API key to Bukki support.