HTTP integration

Request shape

Send GET https://yep.com/api/v1/search with an API key in the Authorization header. Put query, limit, and lang in the URL query string using your HTTP library's URL encoder.

Use a connection timeout and an overall request deadline appropriate for your application. Keep the API key outside application logs.

Response handling

Treat the response as successful only when the HTTP status is in the 2xx range. Decode the JSON body as an object, read ranked results from results, and preserve the X-Request-ID response header with your request telemetry.

Do not infer missing fields or replace an invalid response with defaults. A malformed successful response is an integration failure.

Retries

Retry only requests that are safe for your workload. For 429, wait at least the number of seconds in Retry-After. For 503 with reason: "model_provider_overloaded", honor Retry-After when present; the typed retry recovery also says whether changing the selected model is allowed. For other temporary 502 or 503 responses, use capped exponential backoff with jitter.

Do not automatically retry 400, 401, 402, or 403; correct the request, credential, permissions, or account limit first.

Verify the integration

Test a successful query, an invalid query, an invalid key, product rate limiting, provider throttling, and provider overload before production. Log the HTTP status, stable error reason, request ID, and agent session ID when present, but never the credential or raw sensitive diagnostics.

Use the Search API reference for the generated contract and errors and limits for recovery guidance.