A request can succeed on the server even when the client loses the response. Retrying is reasonable, but the retry should represent the same logical operation rather than pretending the user initiated another search.
GIFs.so accepts an optional UUID requestId on search, category listing, and GIF lookup. Generate it once per logical operation and reuse it with identical parameters when retrying.
Keep the identifier with the request
Store the request ID together with the query, category, limit, and offset. A retry uses that same bundle. A new query or a new page is a new logical operation and should receive a new identifier.
Successful retries with the same identifier and parameters are deduplicated in usage analytics for 30 days. Reusing the identifier with changed parameters returns a conflict. Without a request ID, each successful call is recorded separately.
This is analytics deduplication, not unlimited access. Repeated calls still consume the account’s rate-limit capacity. Do not use the same ID to issue rapid retries against a 429 response.
Decide which failures are retryable
A network timeout or temporary 503 may justify a small, bounded retry sequence. Use delays with jitter so multiple clients do not all retry simultaneously. Stop after a defined attempt count and expose a manual retry state.
A 401 needs access to be fixed. A 404 for an unknown item needs a missing-content state. A 409 means the request ID was reused inconsistently. These conditions are not repaired by sending the same request faster.
A 429 needs time for the relevant rate-limit window to reset. Respect any retry information available and preserve already loaded results while waiting.
Do not confuse retries with new user intent
If the user changes the search while a retry is pending, cancel or ignore the old operation. A successful late retry should never overwrite the current query’s results.
For logs, record the request ID, operation, attempt number, and status. Keep keys and sensitive application context out of the log entry. This makes it possible to explain whether an apparent burst was user activity or recovery work.
See the integration guide for the exact request contract and rate-limit guidance for account-wide limits. Test the “server succeeded, client timed out” case alongside ordinary failed responses; it is the scenario request deduplication is designed to address.