Error Handling and Retry

Failed requests use the common envelope with success: false, data: null, and a structured error.

Field	Use
code	Stable program branch
action	Recommended corrective category
request_id	Server-log correlation and support
message	Human-readable explanation only
details	Optional structured context

Do not branch on localized message text or assume every details field is present.

Retry read-only requests only for transient conditions such as RATE_LIMITED, SERVICE_UNAVAILABLE, or another error with action: RETRY_LATER. Use bounded exponential backoff and fresh timestamp, nonce, and signature.

For create requests, first recover the result through a business identifier such as client_request_id. Authentication, validation, permission, balance, and conflict errors require correction rather than blind retry.

Support reports should include time, endpoint, HTTP status, code, action, and request_id, but never API or HMAC keys.

Decision table

Action	Automated behavior
CORRECT_FIELD_VALUE, PROVIDE_REQUIRED_FIELDS	Fail validation and return actionable feedback
SYNC_SYSTEM_TIME, GENERATE_NEW_NONCE, REGENERATE_SIGNATURE	Repair once, then stop if repeated
CHECK_RESOURCE_ID, REQUEST_ACCESS	Verify environment, ownership, and permission
ADJUST_AMOUNT, INCREASE_BALANCE	Require a new business decision
RESOLVE_CONFLICT	Retrieve current state and reconcile intent
RETRY_LATER	Retry eligible reads with jittered bounded backoff
CONTACT_SUPPORT	Stop automation and preserve diagnostics

Unknown actions and malformed error envelopes fail closed. Preserve safe raw response metadata for analysis.