Errors & rate limits

Status codes

Code	Meaning	What to do
`200` / `201`	Success	—
`204`	Success, no body (e.g. revoke)	—
`401`	Unauthorized	Key is missing, malformed, revoked, or expired. Check the `Authorization` header and the key’s status in Settings → API Keys.
`403`	Forbidden	Authenticated, but not allowed for this resource in this workspace. A key only has your permissions, in its own workspace.
`404`	Not found	The project/task/file id doesn’t exist in this workspace.
`422`	Validation error	The request body is malformed or missing fields. `error.message` says what’s wrong, and `error.param` names the offending field.
`429`	Rate limited	You’re sending too fast. Back off and retry (see below).
`5xx`	Server error	Transient — retry with backoff.

Every error returns the same JSON envelope: an error object with a type, a machine-readable code, a human-readable message, and (on validation errors) the offending param.

{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "Project proj_xxxxxxxxxx not found."
  }
}

Retries and backoff

Retry 429 and 5xx responses with exponential backoff. Do not retry 4xx other than 429 — fix the request instead.

import time, requests

def request_with_retry(method, url, *, headers, max_retries=5, **kwargs):
    for attempt in range(max_retries):
        resp = requests.request(method, url, headers=headers, **kwargs)
        if resp.status_code < 400:
            return resp
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** attempt)  # 1s, 2s, 4s, 8s, 16s
            continue
        resp.raise_for_status()  # non-retryable 4xx
    resp.raise_for_status()
    return resp

Rate limits

Limits apply per workspace to keep the platform stable. If you exceed them you get a 429; slow down and retry with backoff. For sustained high-volume workloads (large batch pipelines), keep concurrency bounded and space out your calls. If you expect to run well beyond normal usage, contact support@phylo.bio so we can make sure your workspace is provisioned for it.

Key lifecycle errors

401 right after creating a key — confirm you copied the full API key (it’s shown only once) and sent it as Authorization: Bearer <your-api-key>.
401 on a previously working key — it may have been revoked or expired. Create a new key and update your integration.

Guides

Reference

Errors & rate limits

Status codes

Retries and backoff

Rate limits

Key lifecycle errors

​Status codes

​Retries and backoff

​Rate limits

​Key lifecycle errors

Status codes

Retries and backoff

Rate limits

Key lifecycle errors