Response Envelope

All REST APIs return JSON. Clients should read both the HTTP status code and the code field in the response body.

Fields

Field	Type	Required	Description
code	string	Yes	Business code. Both success and error codes use uppercase underscore format
message	string	Yes	Human-readable description for display, logs, and troubleshooting only
requestId	string	Yes	Request ID to provide during troubleshooting
data	object	Required for success responses	Response data for successful requests. This field is omitted in error responses

Client Rules

• Clients must branch on HTTP status and code
• Clients must not branch on message
• message may change as wording is refined, but code must remain stable
• Error responses currently do not include field-level error details

Success Response

{
  "code": "SUCCESS",
  "message": "OK.",
  "requestId": "req_001",
  "data": {}
}

Error Response

{
  "code": "AUTH_INVALID",
  "message": "Authentication credentials are invalid.",
  "requestId": "req_001"
}

Design Notes

• Success and error responses keep a unified outer shape
• Error responses omit data to avoid clients misreading an empty response data
• COMMAND_ACCEPTED is a success-class business code and must include data
• The current version does not return field-level error details