Errors, limits, and billing

Error responses

API failures use a stable JSON error body. Branch on the HTTP status and machine-readable reason, not the human-readable message. Include X-Request-ID when contacting support.

• 400 — inspect validation when present, correct every listed request field, then retry.
• 401 — provide a valid, active API key.
• 402 — review billing and spend limits before retrying.
• 403 — use a key with Search API permission.
• 429 — wait for Retry-After, then retry with backoff. Inspect reason to distinguish an account policy (rate_limit_exceeded) from provider throttling (model_provider_rate_limited).
• 503 with model_provider_overloaded — the selected model provider has no temporary capacity. Honor Retry-After when present, or select another allowed model when recovery.can_change_model is true.
• Other 502 or 503 responses — retry temporary service failures with capped backoff and jitter.

Validation errors

A 400 response may include validation, the same bounded report returned by MCP at structuredContent.error.validation:

{
  "code": "invalid_request",
  "reason": "malformed_request",
  "message": "invalid request: request body violates the public contract",
  "recovery": null,
  "agent_session_id": null,
  "validation": {
    "contract": "SearchPostRequest",
    "issues": [
      {
        "code": "required",
        "path": "/query",
        "suggestion": "Add the required `query` field."
      }
    ],
    "truncated": false
  }
}

contract names the published request schema. Each issue has a stable code, an RFC 6901 path, and a suggestion. When allowed_values is present, use one of those exact JSON scalar values. A root error uses an empty path.

Correct every listed issue before retrying. If truncated is true, validate the corrected request again because the report omitted additional issues. Do not retry an unchanged rejected request. Stop if the same output fails again, and use a small fixed repair ceiling for each request. Validation errors are not transient, so backoff does not repair them.

Result and request limits

limit accepts 1 through 50 results. The API has no pagination. Changing the limit can change ranking, so do not combine separate calls as pages of one result set.

Rate limits are enforced by the active account and key policy. The API returns 429 and Retry-After when a request should wait; this documentation does not publish a fixed numeric rate that could differ from the configured policy.

Provider throttling and overload use the same reason and recovery fields as product rate limits. recovery.kind is retry, retry_after_ms preserves the provider hint, and recovery.can_change_model tells an agent client whether selecting another allowed model is a valid recovery. Direct HTTP failures carry Retry-After as the RFC 9110 retry header in whole seconds. Responses with 429 are emitted with Cache-Control: no-store, preserving the RFC 6585 caching requirement.

Every agent execution mints an agent_session_id before calling the model provider. A synchronous REST failure returns it in the error body; MCP returns the same structured error; and a background run keeps it in the accepted response and every polled status. A failed background status remains a successful status lookup (200) whose error contains the same provider reason and recovery. The session id is useful for status and support correlation, but it is not a credential.

Billing

Balanced costs $4 per 1,000 completed requests. A failed search execution is not charged. Account spend limits can reject a request with 402 before execution.

The documentation console sends real API requests. Normal billing, spend limits, and rate limits apply.

Recovery checklist

1. Record the HTTP status, X-Request-ID, and agent_session_id when present.
2. Read the stable error reason.
3. Correct non-retryable failures before sending another request.
4. Honor Retry-After and use jitter for retryable failures.

Return to the HTTP integration guide or inspect the generated API reference.