Error Responses
Handle failures by HTTP status and protocol layer.
Check network and HTTP status first, then parse the endpoint-specific schema. Do not depend on one error field or exact error text.
HTTP handling
| Result | Retry? | Action |
|---|---|---|
400 | No, unless the request changes | Validate JSON, UID, Channel, cursor, and required fields |
503 maintenance | Yes, with bounded backoff | Wait for restore maintenance and observe /readyz |
Other 5xx or network timeout | Conditional | Use exponential backoff, jitter, a cap, and cancellation |
2xx with a schema mismatch | No | Stop processing and inspect version or contract drift |
Common error bodies:
{"msg":"...","status":400}
{"error":"maintenance","message":"restore maintenance is active"}Error text is not a stable machine contract. Branch on HTTP status and schema.
Protocol boundary
HTTP success does not prove CONNECT, SENDACK, realtime delivery, or read success. Handle CONNACK and SENDACK separately using their packet type and Reason Code; stop and report unknown values.
Log safety
- Record method, path, HTTP status, and a separate request ID.
- Do not log tokens, Authorization, cookies, UIDs, message bodies, or complete raw errors.
- Bound retry count, duration, and concurrency.