Response Envelope

Every JSON response (success or failure) carries a status discriminator, keeping branching trivially typed across languages.

Success

{
  "status":  "success",
  "data":    { /* endpoint-specific payload */ },
  "message": "Operation completed successfully",
  "warnings": []
}

warnings[] is optional. When present, it carries non-fatal advisories (e.g. partial config rollback notices, deprecated parameter usage). Treat warnings as informational, not as errors.

Error

{
  "status":     "error",
  "error_code": "ACCOUNT_NOT_FOUND",
  "message":    "Account 'alice' does not exist",
  "details":    { /* optional structured context */ }
}

error_code is the machine identifier; map exception handling on that field, not on the localised message. The full catalog lives in Appendix A.