A failed GIF request and a successful search with no results are different outcomes. Keep them separate in your application state so users receive an action that can actually help.
GIFs.so documents REST errors for authentication, missing content, conflicting request IDs, rate limits, and temporary unavailability. MCP exposes corresponding tool errors through its own response surface.
Match the response to the next action
401: authentication or verified access required. Check the key or session and account verification. Offer a sign-in or access-recovery path in an interactive product. Repeated retries with unchanged credentials will not solve it.
404: unknown GIF or category. Show an unavailable item or clear the invalid filter. Preserve the rest of the conversation or already loaded results. Do not silently substitute a different reaction.
409: conflicting request ID. A request ID was reused with different parameters. Fix the client’s operation identity instead of treating the conflict as a provider outage.
429: rate limit. Pause further requests, respect retry information when supplied, and wait for the relevant window. Keep loaded GIFs visible so the picker is not completely unusable.
503: service unavailable. Use a bounded retry with delay for a temporary failure, then offer a manual retry. Keep ordinary text input usable.
Preserve useful context
For a failed next page, retain previous pages and retry the failed offset. For a failed fresh query, keep the query text so the user does not need to retype it. For a media-load failure after successful search, mark that individual card rather than declaring the API offline.
Log the operation, status, request ID, and elapsed time. Never log the API key. If your server wraps provider errors, retain enough internal detail to diagnose them while returning a clear, stable application error to the frontend.
Test failures deliberately
Exercise each branch with dependency-injected responses or a controlled local fixture. Include malformed JSON, an unexpected successful response shape, and a timeout after the server may have completed the operation.
The integration guide defines current behavior. Retry guidance explains request-ID reuse, and the React picker article covers stale requests. A useful failure state is part of the picker, not an error message added after the happy path is finished.