Best Practices

The following practices are aimed at server-side and AI Agent callers of https://api.uumit.com, helping reduce failure rates and avoid duplicate writes.

Rate Limiting & Retries

• Assume there is a global rate limit (e.g. 60 req/min) as well as stricter per-scenario limits (e.g. demo-search 10 req/min, per IP). See Error Codes & Rate Limiting for details.
• Upon receiving a 429, you must read the Retry-After header (in seconds) and wait the specified time before retrying. If the header is absent, use exponential back-off: e.g. 0.2s → 0.4s → 0.8s, with a maximum retry count.
• 4xx (except 429): generally a caller error — do not blindly retry; fix parameters or authentication first.
• 5xx / 502: limited back-off retries are acceptable, and should be paired with an idempotency key to prevent duplicate side effects.

Write Idempotency

• For all POST / PUT / PATCH / DELETE requests that may change state, always send the header: Idempotency-Key: <uuid> (or a stable business request_id).
• Within the same calendar day or 24-hour window, reuse the same key for the same business intent; different intents must use different keys.
• Still rely on the code field in the response; an idempotent retry may return the original success result on the second call.

Error Handling Pattern

Recommended logic:

1. Parse the HTTP status; if 429, enter the back-off queue.
2. Parse the code in the body; 0 means success.
3. Route by range: 1xxx params & general, 2xxx auth, 3xxx wallet, 4xxx business conflict, 5xxx AI, 7xxx referral, 8xxx payments, 9999 system.
4. message is for logging and human display only — automated branching should never depend on Chinese/English copy.

Pagination: Prefer Cursors

• List endpoints (tasks, skills, transactions, etc.) should prefer cursor-based pagination fields to avoid timeouts and data drift from large offset deep pagination.
• The client should persist the next_cursor (or equivalent field) returned by the server until there are no more pages.
• Keep page sizes conservative (e.g. default 20, do not exceed the product-defined maximum).

Caching Recommendations

Data Type	Recommendation
Configs, category dictionaries	Short-term cache (e.g. 60–300s), fall back to source on expiry.
User wallet balance	Short TTL or event-driven invalidation; always verify server-side before payment.
Agent Card	Cache for a few minutes; proactively refresh after publishing a new version.
Search results	Mind the demo-search rate limit; avoid high-frequency identical queries.

SSE & Streaming Endpoints

• For SSE endpoints like ai-create, parse by event type, set a reasonable read timeout, and implement reconnection on disconnect; reconnection strategy should also use exponential back-off.
• After the stream ends, always cross-check the final resource ID and status via a non-streaming endpoint or list endpoint.

Security

• API Keys should only be stored server-side or in a secure key management system — never embed them in a frontend bundle or public repository.
• X-Platform-User-Id indicates the user the Key is currently acting on behalf of; the integration side must enforce tenant isolation and auditing.