Errors & rate limits

The API uses conventional HTTP status codes with a consistent JSON error envelope. Every response carries X-Quickli-Request-Id — quote it when contacting support.

Error envelope

error-response.json
// Every error response
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "dropoff.location.address is required",
    "docUrl": "https://enterprise.quickliapp.com/docs/errors#VALIDATION_ERROR",
    "requestId": "req_8f2k3j…",
    "details": [
      { "field": "dropoff.location.address", "issue": "required" }
    ]
  }
}

Error codes

HTTPCodeMeaning
400BAD_REQUESTMalformed JSON or missing required headers.
401UNAUTHORIZEDMissing, invalid or malformed API key.
401KEY_REVOKEDThis key was revoked. Create a new one in the portal.
403SCOPE_MISSINGKey is valid but lacks the scope for this endpoint.
403ORG_SUSPENDEDOrganization suspended — contact support.
402TOKENS_EXHAUSTEDToken balance is 0. Top up to resume writes (reads stay up for 24h grace).
402WALLET_INSUFFICIENTNaira wallet cannot cover this delivery. Fund it and retry.
404NOT_FOUNDResource does not exist or belongs to another organization.
409IDEMPOTENCY_CONFLICTSame Idempotency-Key reused with a different payload.
422VALIDATION_ERRORField-level problems listed in error.details.
422GEO_OUT_OF_SERVICE_AREAPickup or dropoff outside Quickli-served cities.
429RATE_LIMITEDPlan rate limit exceeded. Honour Retry-After and back off exponentially.
500INTERNAL_ERROROur fault — not metered, safe to retry with the same Idempotency-Key.

Rate limits

Limits are per API key, set by your plan (60–600 requests/minute, with short bursts allowed). Every response includes:

rate-limit-headers
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1763044800
Retry-After: 12          // only on 429

On 429, back off exponentially with jitter. Sustained 429s trigger an alert in your portal and to our ops team — we would rather upgrade your plan than throttle your business.

Metering rules

usage-headers
X-Token-Cost: 5            // tokens this request consumed
X-Token-Balance: 148320    // remaining balance after debit

5xx responses are never metered. 4xx responses cost 1 token (abuse deterrent). Idempotent replays return the original response and cost nothing extra.

Idempotency

Send Idempotency-Key: <unique-per-logical-operation> on every POST. Keys are remembered for 24 hours:

idempotency
# First request  → processed normally, response cached
# Retry (same key, same body) → cached response replayed, HTTP 200, no re-meter
# Same key, DIFFERENT body   → 409 IDEMPOTENCY_CONFLICT

Retrying safely

On timeouts or 5xx, retry with the same Idempotency-Key. You will either get the original result or a fresh execution — never a duplicate delivery or double charge.