Handle errors and retries

Every error is an RFC 9457 problem document with a stable error_code and, when there is a self-service fix, a resolve object that says who fixes it and where. Branch on error_code, not on the status alone: two 402s can mean “add a credential” and “stop, the plan needs attention”, and only one of them is worth retrying.

The envelope

{
  "type": "https://docs.particle.pro/errors/validation_error",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The q parameter is not supported on this endpoint. To search for a person, company, or knowledge graph entity by name, nickname, stock ticker, @handle, or domain, use GET /v1/entities/search (e.g. /v1/entities/search?q=sam+altman). This endpoint lists the most-mentioned entities and filters by type, podcast_id, or ids.",
  "error_code": "validation_error"
}

That is a real response to GET /v1/entities?q=altman. detail names the endpoint to use and gives a worked example; a 422 from a bad parameter names the parameter in errors[]. Read it once, change the request, and send it once.

What to do by status

Status	`error_code`	What it means	What to do
400, 422	`bad_request`, `validation_error`, `unresolved_reference`	The request is malformed or names something that does not resolve	Read `detail` and `errors[]`, fix the request, send it once. Never resend it unchanged.
401	`api_key_required`	No usable key: missing, mistyped, revoked, or expired all get this response	Check the header (`X-API-Key`) and the key at platform.particle.pro/tokens.
402	`payment_required`	The request carried no credential	Add a key, or pay per request with x402.
402	`no_active_plan`, `spend_limit_exceeded`, `credits_depleted`, `payment_delinquent`, `subscription_suspended`	The organization’s billing state blocks the call	Stop the loop. `resolve.action` and `resolve.url` say what fixes it and who can; retrying cannot change it.
403	`enterprise_required`, `not_a_member`, `forbidden`	The credential is valid but not entitled	Check the plan or the project the credential is scoped to; an OAuth grant for the wrong project is the usual cause.
404	`not_found`	The id does not resolve	If it is a slug you built, resolve the name instead; if it is a podcast slug on an episode endpoint, list the show’s episodes first. Do not try spellings.
429	`rate_limit_exceeded`	Over 10,000 requests per minute for the organization	Wait `Retry-After` seconds, then continue.
5xx	`internal_error`	Something failed on our side	Back off exponentially with jitter and retry a bounded number of times; quote `X-Trace-ID` if it persists.

Two 402 codes deserve emphasis because they are the ones clients retry into the ground: spend_limit_exceeded and credits_depleted do not clear on their own, and every retry is another rejected request. Surface resolve.message to the person who owns the account and stop.

A retry wrapper

Retry only where the table says to, and let the server pace you.

async function particle(url, { attempts = 5 } = {}) {
  if (!Number.isInteger(attempts) || attempts < 1) throw new RangeError("attempts must be a positive integer");
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(url, { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } });
    if (res.ok) return res.json();

    const problem = await res.json().catch(() => ({}));
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt >= attempts) {
      throw new Error(`${res.status} ${problem.error_code ?? ""}: ${problem.detail ?? ""}`);
    }
    const retryAfter = Number(res.headers.get("Retry-After"));
    const delay = retryAfter > 0 ? retryAfter * 1000 : Math.min(30_000, 500 * 2 ** attempt) * (0.5 + Math.random());
    await new Promise((r) => setTimeout(r, delay));
  }
}

import os, random, time, httpx

def particle(url, params=None, attempts=5):
    if attempts < 1:
        raise ValueError("attempts must be at least 1")
    headers = {"X-API-Key": os.environ["PARTICLE_API_KEY"]}
    attempt = 0
    while True:
        attempt += 1
        res = httpx.get(url, params=params, headers=headers)
        if res.is_success:
            return res.json()
        problem = res.json() if res.headers.get("content-type", "").startswith("application/problem+json") else {}
        retryable = res.status_code == 429 or res.status_code >= 500
        if not retryable or attempt >= attempts:
            raise RuntimeError(f"{res.status_code} {problem.get('error_code', '')}: {problem.get('detail', '')}")
        retry_after = float(res.headers.get("Retry-After", 0) or 0)
        delay = retry_after if retry_after > 0 else min(30, 0.5 * 2 ** attempt) * (0.5 + random.random())
        time.sleep(delay)

The wrapper never retries a 4xx other than 429, so a billing state, a bad parameter, or a constructed slug surfaces as one clear exception instead of a burst of identical requests.

Parameters that cause avoidable errors

Omit optional parameters you do not need. A placeholder such as x, -, or __omit__ is a real filter value; it fails validation or matches nothing.
One name per concept. q is the free-text query wherever one exists (/v1/podcasts/search, /v1/companies, /v1/entities/search); /v1/entities lists and filters and takes no q. Sending q, query, and search together does not hedge; it trips validation.
Slugs come from responses. A constructed slug returns 404; resolve the name and take the slug from the result. See From an empty page to the data.

Errors overview for the full code catalog and the resolve contract
Concepts for authentication and rate limits
Pay per request with x402 for the keyless 402 flow

Getting started

Recipes

Podcasts

Companies

Knowledge graph

Alerts

Errors

Handle errors and retries

The envelope

What to do by status

A retry wrapper

Parameters that cause avoidable errors

​The envelope

​What to do by status

​A retry wrapper

​Parameters that cause avoidable errors

​Related

The envelope

What to do by status

A retry wrapper

Parameters that cause avoidable errors

Related