14.5. Common Response Status

GEISA Application Programming Interface

14.5.1. Summary

GEISA request/response APIs that include GeisaStatus use it as a common response status and error model. The common status is used for request/response result handling and does not replace API-specific response fields that provide additional context for a particular API.

This model is distinct from the Platform/App Status notification API described in Platform and App Status. Platform/App Status notifications report runtime platform or application status over status topics; GeisaStatus reports the result of a request/response transaction where the response message includes it.

14.5.2. Status Message Model

GeisaStatus contains:

  • code: a GeisaStatusCode machine-readable result that should drive application behavior.

  • message: a short human-readable explanation suitable for logs, diagnostics, or UI.

  • details: optional diagnostic text. To ensure interoperable behavior, Applications MUST NOT parse details or take action based on its contents.

GEISA_STATUS_SUCCESS indicates success.

GEISA_STATUS_CODE_UNSPECIFIED MUST NOT be treated as success unless an API explicitly says otherwise.

14.5.3. Status Code Handling

Applications should branch primarily on code. Human-readable message and details values are for diagnostics and display, not interoperable control flow.

Table 14.2 Status Code Handling

Group

Codes

Expected application behavior

Success

GEISA_STATUS_SUCCESS

Treat the request as successful, subject to any API-specific response semantics.

Request/protocol errors

GEISA_STATUS_CODE_REQUEST_*

Fix the request before retrying; unchanged retries usually repeat the same error.

Authorization/policy errors

GEISA_STATUS_CODE_AUTH_*

Resolve permission or policy configuration; do not retry unchanged.

Resource, limit, busy, or state errors

GEISA_STATUS_CODE_RESOURCE_*

Retry only when appropriate, using bounded backoff or after the relevant platform state changes.

Execution/platform/dependency errors

GEISA_STATUS_CODE_EXEC_*

Treat as potentially transient or platform-side according to API context; log sufficient diagnostics for triage.

Data quality or availability conditions

GEISA_STATUS_CODE_DATA_*

Treat the response as completed, but handle data that may be unavailable, stale, incomplete, or otherwise limited.

14.5.4. API Usage

The current schemas define GeisaStatus on these response messages:

  • GeisaPlatformDiscovery_Rsp

  • GeisaWaveform_Rsp

  • GeisaActuatorSet_Rsp

  • GeisaActuatorGet_Rsp

  • GeisaSensorReadings_Rsp

Some response messages include additional API-specific status or detail fields. Those fields provide API-specific context in addition to the common status code; they do not replace GeisaStatus where it is present.

GeisaAppMessage_Rsp uses its own app-message response status field and is not defined with GeisaStatus in the current schemas.

14.5.5. Implementation Guidance

Applications should branch primarily on the GeisaStatusCode value. Applications should not parse message or details for interoperable behavior.

Logs should include the status code and relevant request identifiers where available. Applications should use bounded retry and backoff for retryable conditions rather than tight retry loops.

Platforms should return the most specific applicable status code and include human-readable diagnostics where useful. Platforms should not use success with partial or invalid data unless the API explicitly defines partial-success semantics.

14.5.6. Transaction Data

  • GeisaStatus

  • GeisaStatusCode

As defined in https://github.com/geisa/schemas

GEISA Pyramid