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.
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.