API Responses

Standard Response Envelope

API endpoints under /api/openapi/v1 return HTTP 200 OK and use the same response envelope:

{
  "code": "C00000",
  "msg": "success",
  "data": {}
}

Field	Description
code	response body code. API Reference examples use C00000.
msg	Human-readable result or error message.
data	Response payload. This is null when no response data is available.

OAuth2 endpoints such as /authorize and /token follow the OAuth2 response format and do not use this envelope. Authentication, authorization, rate-limit, and related infrastructure responses also use the separate formats documented below.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": "C00000",
  "msg": "success",
  "data": {
    "total": 4,
    "page": 1,
    "size": 20,
    "devices": []
  }
}

Authentication and Infrastructure Responses

These responses are produced outside the standard API response flow and do not use the standard response envelope. Authentication and resource authorization failures use message and reason fields.

HTTP status	Trigger	Default response body
401	Missing authorization header or otherwise invalid token input.	{"message":"Unauthorized","reason":"missing Authorization header"}
401	The token is no longer active.	{"message":"Unauthorized","reason":"token is not active"}
401	The client identity required for the resource check is missing.	{"message":"Unauthorized","reason":"missing client_id for resource check"}
403	User information is missing.	{"message":"Forbidden","reason":"no permission for this resource"}
403	The client has no permission for a single resource.	{"message":"Forbidden","reason":"no permission for this resource"}
403	The client has no permission for a resource in a batch request.	{"message":"Forbidden","reason":"no permission for resource: {resourceId}"}
429	The applicable request-rate limit has been exceeded.	{"message":"Too Many Requests","reason":"Rate limit exceeded: 2 requests per minute per device."}
503	The authentication service is unavailable.	{"message":"Service Unavailable","reason":"token introspection failed"}
503	The resource-check cache or backend service is unavailable.	{"message":"Service Unavailable","reason":"resource check backend error"}

Rate-limit Response

When the applicable request-rate limit is exceeded, OpenAPI returns HTTP 429 Too Many Requests instead of the standard response envelope.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "message": "Too Many Requests",
  "reason": "Rate limit exceeded: 2 requests per minute per device."
}

See Rate Limits for the quota table.

Response Body Codes

API results use HTTP status 200 with one of the following codes in the response body envelope.

HTTP status	Body code	Default msg
200	C00000	success
200	B01601	partial success
200	C01001	parameter is missing
200	C01002	parameter format is invalid
200	C01003	parameter is out of range
200	C01004	duplicate parameter
200	C01005	parameter mismatch
200	C01006	parameter length exceeds the limit
200	C01007	invalid parameter value
200	C02001	resource not found
200	C02002	station not found
200	C02003	device not found
200	C03001	unauthorized
200	C03003	access denied
200	C04001	internal error
200	C04003	dependency service error
200	C04004	database error
200	C04005	cache error
200	C05001	business rule conflict
200	C05002	invalid state
200	C05003	operation not allowed
200	C05004	data already exists
200	C05005	limit exceeded
200	C05006	resource is occupied