For AI agents: the complete documentation index is available at https://payhon.github.io/AppKernia/en-US/llms.txt, the full documentation bundle is available at https://payhon.github.io/AppKernia/en-US/llms-full.txt, and this page is available as Markdown at https://payhon.github.io/AppKernia/en-US/api/conventions.md.
AppKernia

Responses, errors, and idempotency

Success:

{
  "code": "OK",
  "message": "success",
  "data": {},
  "request_id": "01900000-0000-7000-8000-000000000001"
}

Error:

{
  "error": {
    "code": "IAM.AUTH.INVALID_CREDENTIALS",
    "message_key": "errors.iam.auth.invalid_credentials",
    "message": "Invalid email or password",
    "details": {}
  },
  "request_id": "01900000-0000-7000-8000-000000000001"
}

Clients branch on stable error.code or message_key, never on message.

StatusMeaningClient behavior
400Malformed requestFix the request
401Invalid session or expired access tokenOne single-flight refresh
403Authenticated but unauthorizedDo not refresh
404Missing or invisible resourceDo not infer cross-tenant existence
409Version or state conflictReload and resolve explicitly
422Field validationMap details to local fields
429Rate limitedHonor Retry-After

Send Accept-Language: zh-CN or en-US; read Content-Language. Codes and raw values do not change with language.

Admin lists commonly use page and page_size. Mobile notifications and articles use opaque cursors; clients must not parse a cursor.

GET and HEAD may use limited backoff. POST, PATCH, and DELETE are not retried by default. Replay a write only when its contract explicitly supports Idempotency-Key.