Errors & quotas

All errors share one envelope:

json
{
    "error": {
        "code": "rate_limited",
        "message": "..."
    }
}

SDKs turn this into a native exception (FivexerApiError, FivexerApiException, etc.) with status, code, message, and — on 402/429 — the current quota snapshot.

Quota headers

Every response carries X-Quota-* headers parsed onto client.quota:

• x-quota-task-rate-limit / x-quota-task-rate-remaining
• x-quota-queued-tasks-limit / x-quota-queued-tasks-remaining
• x-quota-workers-limit / x-quota-workers-remaining
• x-quota-skills-limit / x-quota-skills-remaining

Monitor task_rate_remaining and back off before you hit zero.

Monthly matched-task quota

Separately from those per-request limits, each workspace includes a number of matched tasks per UTC calendar month:

A sandbox is a demo surface, not a smaller plan — every other limit matches the free plan. Note that a sandbox reset wipes the routing data but deliberately keeps the meter, so repeated resets still count against the month.

Running out does not reject writes. On the free tier, exhausting the meter pauses matching: POST /tasks keeps returning 202 and tasks keep queuing, they simply stop being assigned until the meter resets. Nothing is dropped. That means you will never see a 402 for the monthly quota — what you'll see is the queue growing, and eventually a 402 plan_limit_exceeded carrying x-quota-queued-tasks-* once maxQueuedTasks fills.

Read the meter programmatically from GET /v1/stats:

json
{
    "meter": { "period": "202607", "matchedTasks": 8412, "includedTasksPerMonth": 10000 }
}

Retry behavior

SDKs retry once by default on:

• 429 Too Many Requests — honoring Retry-After if present
• 5xx server errors

POST /tasks automatically sends an Idempotency-Key header, so a retried create is deduplicated safely.

Common error codes