Parallel AI API Error Reference and Retry Strategies

Error Response Format

Every error response from the Parallel AI API returns a JSON body with a single error field describing what went wrong:

{
  "error": "Description of what went wrong"
}

Always check both the HTTP status code and the error message when debugging — the message provides specific context that the status code alone cannot.

HTTP Status Codes

Code	Meaning	Common Cause
`200`	Success	—
`201`	Created	Resource successfully created
`400`	Bad Request	Missing required field or invalid parameter value
`401`	Unauthorized	Missing, invalid, or expired API key
`403`	Forbidden	Feature not available on your current plan
`404`	Not Found	Resource ID does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server-side error

Common Errors and Solutions

401 Unauthorized — invalid or missing API key

Symptom: You receive {"error": "Unauthorized"} on every request.Solutions:

Confirm you’re sending the X-API-Key header (or Authorization: Bearer ...) with every request.
Verify the key is correct — copy it fresh from the dashboard to rule out typos.
If you’re using a Personal Access Key (PAK), you must also include the X-Company-ID header:

curl "https://api.parallellabs.app/api/v0/agents" \
  -H "Authorization: Bearer pak_your_key" \
  -H "X-Company-ID: your_company_id"

403 Forbidden — feature not enabled on your plan

Symptom: Your request is authenticated but returns {"error": "Forbidden"}.Solutions:

The endpoint or feature you’re calling may not be included in your current Parallel AI plan.
Contact Parallel AI support to confirm which features are available on your plan or to request access.

404 Not Found — resource does not exist

Symptom: A resource lookup returns {"error": "Not found"}.Solutions:

Double-check the resource ID in your request path (e.g. agent ID, sequence ID).
Confirm the resource belongs to the company associated with your API key — you cannot access resources from other companies.
The resource may have been deleted. Use a list endpoint to verify it still exists.

429 Too Many Requests — rate limit exceeded

Symptom: Requests start returning {"error": "Too many requests"}.Solutions:

Slow down the rate at which you’re making requests.
Implement exponential backoff: wait before retrying, doubling the wait time on each successive failure.
Batch operations where possible, or use pageSize=100 to retrieve more data per request.

500 Internal Server Error

Symptom: The API returns a 500 status unexpectedly.Solutions:

This indicates an issue on Parallel AI’s servers, not your request.
Retry the request after a short delay — most transient errors resolve quickly.
If the error persists, contact Parallel AI support with the request details and timestamp.

Retry Logic with Exponential Backoff

For production integrations, implement retry logic to handle transient errors (429 and 500) gracefully:

import requests
import time

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            wait = 2 ** attempt  # 1s, 2s, 4s
            print(f"Rate limited. Retrying in {wait}s...")
            time.sleep(wait)
            continue

        response.raise_for_status()
        return response.json()

    raise Exception("Max retries exceeded")

Add jitter (a small random delay) to your backoff to prevent multiple clients from retrying simultaneously and creating a thundering-herd effect:

import random
wait = (2 ** attempt) + random.uniform(0, 1)
time.sleep(wait)

Do not retry 400, 401, 403, or 404 errors — these indicate problems with your request or credentials that will not resolve on their own.

Get Started

Core Features

Integrations

Platform

Parallel AI API Error Reference and Retry Strategies

Error Response Format

HTTP Status Codes

Common Errors and Solutions

Retry Logic with Exponential Backoff

​Error Response Format

​HTTP Status Codes

​Common Errors and Solutions

​Retry Logic with Exponential Backoff

Error Response Format

HTTP Status Codes

Common Errors and Solutions

Retry Logic with Exponential Backoff