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 API path is unknown, or the scoped notification or source does not exist. |
| 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.
Authenticated source-key responses include RateLimit-Policy ("source-key";q=<requests>;w=60) and RateLimit ("source-key";r=<remaining>;t=<seconds>). The quota is shared by all public API operations using the same key. Values reflect the request just processed; r is the remaining request count and t is seconds until that window resets. A 429 also includes Retry-After; honor that delay before retrying. A 401 has no per-key counter because the key was not authenticated.
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.