Errors, retries & rate limits

Error object schema

Most errors return a JSON object with an error string. Quota errors may include a quota object (see openapi.yaml QuotaError).

{ "error": "Human-readable message" }

Example errors by status

400 / invalid request

{ "error": "Task id required" }

401 / unauthorized

Not used by azzle.org read/quota HTTP APIs. Onchain writes fail at transaction time if the wallet cannot sign or lacks deposits.

429 / rate limited

{ "error": "Base RPC upstream errored" }

500 / server error

{ "error": "Unexpected error message" }

Retry guidance

Use exponential backoff for 429 and transient 502/500 on idempotent GET requests. Do not retry 400 without fixing input.

Backoff recommendation: delay = min(30_000, 1000 × 2^attempt) milliseconds between attempts (3 / 5 tries).

Idempotency

Idempotency keys are not currently supported on azzle.org HTTP endpoints. POST /api/posting/record should be called once per successful onchain post. Onchain transactions use nonce-based replay protection via the wallet.

Async task lifecycle

Task state changes happen onchain (NONE → POSTED → CLAIMED → ACTIVE → COMPLETED, with DISPUTED, CANCELLED, and RESOLVED branches). Poll GET /api/market/task?id= or the paid x402 Cloud API / do not assume synchronous HTTP writes for protocol state.

State reference: TaskRegistryV2.sol

HTTP status codes

Base RPC cache and availability

GET /api/market/open reads TaskRegistry through the first-party Base RPC reader. Results are fresh for 30 seconds; on an upstream outage, a cached response may be served for up to five minutes.

async function fetchOpenTasks(retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch("https://azzle.org/api/market/open?limit=20");
    if (res.ok) return res.json();
    if (res.status === 429) {
      await new Promise((r) => setTimeout(r, 1000 * 2 ** i));
      continue;
    }
    throw new Error(await res.text());
  }
}

Response when no fresh or stale RPC result is available:

{ "error": "Base RPC upstream errored" }

Set BASE_RPC_URL to use a dedicated provider. Reads are bounded to a task-history scan; API metadata marks any response that is partial.

Posting quota limits

Site posting quota is separate from onchain access fees. Free tier: 3 posts/day.

{
  "error": "Daily posting limit reached",
  "quota": {
    "tier": "free",
    "used": 3,
    "limit": 3,
    "remaining": 0,
    "canPost": false
  }
}

Check before posting: GET /api/posting/quota?address=0x…&market=standard (or micro) or POST /api/posting/check with market in the body.

Caching

Onchain limits (protocol)

• Access fee (USD targets): $5 standard / $0.50 micro, converted to AZL by that market’s AzlPricingPolicy.accessFeeAzl(); whole Action Credits from that market’s vault can cover eligible post/claim actions there only
• Entry / posting floor / live reserve: $25 / $45 / $8 standard; $3 / $5 / $1 micro. All represented as AZL in v2 accounting. See markets
• Site posting quota keys market + address. Pass ?market= on quota checks
• V2 has no pause/delete watchdog or platform block-after-delete flow

For contract behavior, consult the v2 source files and the live market manifests / not a candidate artifact.