Skip to main content
For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending .md to its URL or sending Accept: text/markdown.For Search and Extract, use /v1/search and /v1/extract for all new integrations and agent tool calls. Use /v1beta/search and /v1beta/extract only when maintaining an existing integration that already uses them. The request bodies changed too: on /v1/extract, full_content, fetch_policy and excerpt_settings go inside advanced_settings, and sending the v1beta top-level excerpts, full_content and fetch_policy to /v1/extract returns a 422. Do not substitute /v1 for the documented FindAll or Ingest endpoint paths.
The Task API may return various warnings and errors during operation. This page documents the possible error types you might encounter when using the API.

​
Errors

Errors result in a failure to process your request and are returned with appropriate HTTP status codes (4xx or 5xx).

​
Warnings

Warnings indicate potential issues that don’t prevent the request from being processed but may affect results.

​
Warning Handling

The Task API uses a warning system to provide guidance without blocking execution. Warnings are generated during validation and can be handled in two ways:

​
Basis Properties

It is recommended to use FieldBasis in the run output rather than requesting similar information in the output schema. This means you’ve included fields like citations, reasoning, or sources in your output schema, but this information is already provided automatically in every Task Run result through the Basis feature. What is Basis? Every Task Run result includes a basis array containing citations, reasoning, and confidence levels for each output field. This is provided automatically; you don’t need to request it in your schema. Why not include these in the output schema?
  • Redundant: You’ll get duplicate data, wasting tokens and processing
  • Less structured: The automatic Basis provides properly structured citations with URLs and excerpts
  • Less reliable: Asking the model to generate its own citations may produce less accurate results than the built-in citation tracking
The following field names trigger this warning:
  • citations
  • confidence
  • evidence
  • reasoning
  • source
  • sources
  • source_urls
Instead of this:
Do this:
Then access output.basis in the response to get citations, reasoning, and confidence for each field. See Accessing Research Basis for details.

​
Error Reference

​
Error Response Format

All errors return a consistent JSON structure:
For validation errors (422), the detail field contains specific information about which fields failed validation and why.

​
402 Payment Required Troubleshooting

A 402 error indicates your account has insufficient credits to process the request. This can occur even if your account shows a positive balance due to in-flight balance reservations.

​
Understanding In-Flight Balance

When you submit a task, the system reserves credits for the estimated cost before processing begins. This reservation is called the “in-flight balance.” Your available balance equals your total balance minus the in-flight balance from all currently running tasks. Example scenario:
  • Account balance: $10.00
  • 5 running pro tasks (each reserves ~0.10):0.10): 0.50 reserved
  • Available balance: $9.50
If your available balance is insufficient for a new task, you’ll receive a 402 error even though your total balance appears positive.

​
Common Causes

​
How to Resolve

  1. Check your balance: View your current balance and usage at platform.parallel.ai
  2. Wait for tasks to complete: In-flight reservations are released when tasks finish
  3. Add credits: Top up your account balance if genuinely low
  4. Reduce concurrency: Lower the number of parallel tasks to reduce reserved credits
  5. Use lower-tier processors: Reserve fewer credits per task by using base or lite processors where appropriate
For high-volume workloads, monitor your available balance (not just total balance) and implement backoff logic when approaching limits. See Pricing for processor costs.

​
429 Too Many Requests troubleshooting

A 429 error means you exceeded the rate limit for an endpoint. You can receive a 429 even when your logs show fewer requests than your limit in any single clock minute.

​
Rolling-window rate limiting

Parallel enforces per-minute rate limits over a rolling one-minute window, not per calendar minute. Each new request counts against all requests you sent in the past 60 seconds, regardless of where clock-minute boundaries fall. Example scenario:
  • Rate limit: 600 requests per minute
  • 300 requests sent at 12:00:49
  • 300 requests sent at 12:01:00
The requests fall in different clock minutes, but all 600 were sent within the same 60-second window. Further requests are throttled until the requests from 12:00:49 are more than one minute old.

​
How to resolve

  1. Wait for the window to roll over: Once the rate limit is hit, requests are throttled until earlier requests become more than one minute old
  2. Retry with exponential backoff: Space out retries instead of resending immediately
  3. Smooth out bursts: Spread requests evenly over time rather than sending large batches at once
  4. Request higher limits: Contact support@parallel.ai if your workload needs more capacity