FYInbox docs
Errors and retries
Branch on HTTP status and stable error code, preserve unknown codes, honor Retry-After, and avoid replaying ambiguous non-idempotent mutations.
Public error contract
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_request | JSON, fields, or values are invalid. |
| 401 | unauthorized | The bearer key is missing, invalid, or revoked. |
| 404 | not_found | The scoped notification or source no longer exists. |
| 409 | conflict | The requested metadata mutation conflicts with current state. |
| 409 | quota_exceeded | The source cannot store another notification. |
| 413 | payload_too_large | The raw HTTP body exceeds the request limit. |
| 429 | rate_limited | The shared per-key request window is exhausted. |
| 500 | internal_error | The server could not complete the request. |
Errors use { error, message? }. Clients should retain unknown non-empty error codes so the service can add a new code without turning a parseable failure into an opaque one.
Retry policy
Validate locally
Fix 400, 401, 404, 409, and 413 responses before sending the same operation again.
Honor rate limiting
For 429, wait for Retry-After when the delay fits your total deadline, then retry conservatively.
Treat ambiguity explicitly
A notification read is safe to retry. A network failure or 5xx may happen after a write commits: retry create only with a stable deduplicationKey, and do not automatically replay metadata mutations.
Keep diagnostics safe
Record status, stable error code, and X-Request-ID when present, but never log the bearer key or full sensitive payload.