# Errors and rate limits

Handle failed requests without losing evidence or repeating paid work unnecessarily.

Documentation index: https://webcite.co/llms.txt
Canonical page: https://webcite.co/api-docs/errors
API origin: https://api.webcite.co
Authentication: x-api-key header. Keep keys on your server.

## Check the HTTP status

Treat any documented 2xx response as HTTP success, then inspect its result. Some V1 POST handlers return 201 although the OpenAPI response is listed as 200. The examples check the full success range.

- 400: invalid request or an operation-specific refusal, including insufficient credits in affected V1 flows. Read the message.
- 401: missing or invalid authentication. Check the key and environment.
- 403: access to the requested resource is not permitted.
- 404: the requested resource is unavailable.
- 413: input exceeds an accepted size. Reduce it.
- 429: request limit reached. Wait for the supplied retry interval.
- 5xx: a service or dependency failed. Inspect the response before retrying.

After an SSE response begins, errors arrive as events even though the HTTP status was successful. An `error` event or a missing `done` is not a completed verification.

## Rate limits

Default configured request limits are Free: 50 per minute and 500 per day; Builder: 100 per minute and 5,000 per day; Enterprise: 500 per minute and 50,000 per day. Deployments may override these values, and some operations use stricter limits.

Read `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` when returned. A 429 body can include `retryAfter` in seconds. The published guard enforces request windows; do not rely on the old docs' concurrent-request table as an enforced guarantee.

## Use bounded retries

For a 429, wait for the supplied interval. For a transient service failure, use a small retry budget with increasing delays. Do not retry validation or authentication errors unchanged.

A timeout does not prove the server did no work. Save completed responses and operation IDs. JSON verification supports `Idempotency-Key` on JSON POST `/api/v1/verify` (MCP `verify_claim` uses optional `idempotency_key`). Retry the same payload and key within 24 hours; a changed payload returns 409. In-flight or uncertain accounting returns 503 and requires reconciliation. This does not guarantee idempotent streaming, batch retries, or automatic refunds. Poll an existing ask job instead of submitting the same question again.