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
| HTTP | Code | Meaning |
|---|---|---|
| 400 | BAD_REQUEST | Malformed JSON or missing required headers. |
| 401 | UNAUTHORIZED | Missing, invalid or malformed API key. |
| 401 | KEY_REVOKED | This key was revoked. Create a new one in the portal. |
| 403 | SCOPE_MISSING | Key is valid but lacks the scope for this endpoint. |
| 403 | ORG_SUSPENDED | Organization suspended — contact support. |
| 402 | TOKENS_EXHAUSTED | Token balance is 0. Top up to resume writes (reads stay up for 24h grace). |
| 402 | WALLET_INSUFFICIENT | Naira wallet cannot cover this delivery. Fund it and retry. |
| 404 | NOT_FOUND | Resource does not exist or belongs to another organization. |
| 409 | IDEMPOTENCY_CONFLICT | Same Idempotency-Key reused with a different payload. |
| 422 | VALIDATION_ERROR | Field-level problems listed in error.details. |
| 422 | GEO_OUT_OF_SERVICE_AREA | Pickup or dropoff outside Quickli-served cities. |
| 429 | RATE_LIMITED | Plan rate limit exceeded. Honour Retry-After and back off exponentially. |
| 500 | INTERNAL_ERROR | Our 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 429On 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 debit5xx 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_CONFLICTRetrying 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.