Errors and rate limits

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.

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.

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.