Docs

Rate limits and quotas

Per-key request rates, monthly quotas and what counts as billable.

Two limits apply: a rate limit on how fast you can call the API, and a monthly quota on how many billable enrichments you can make. Both depend on your plan; see Pricing.

Rate limit

Each API key has a requests-per-second limit with a small burst allowance, so short spikes are fine.
Every request counts, including requests that return no merchant and requests that fail. A batch is one request.
Above the limit you get 429 with the code rate_limited and a Retry-After header in seconds.

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{"error": {"code": "rate_limited", "message": "Rate limit of 2 requests per second exceeded. Retry after the Retry-After header.", "request_id": "req_…"}}

Need more throughput for a backlog? Use batch: 100 descriptors cost one request against the rate limit.

Monthly quota

An enrichment is billable when it returns a merchant, whether the answer came from the cache or the AI. Results with merchant: null are free.
Quotas follow UTC calendar months and reset on the 1st.
When the quota is used up, enrichment requests return 402 with the code quota_exceeded.
A batch with more items than your remaining quota is rejected as a whole, so you never get a partial batch.

Checking your usage

GET /v1/usage returns your plan, how much of this month's quota you have used, what remains, and a daily breakdown. See the reference.

Try it

Runs through the playground, no key needed

curl https://api.descriptorapi.com/v1/enrich \ -X POST \ -H "Authorization: Bearer $DESCRIPTORAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"descriptor": "POS 4521 CAREEM*RIDE DXB AE", "country": "AE", "mcc": "4121"}'

body := strings.NewReader(`{"descriptor": "POS 4521 CAREEM*RIDE DXB AE", "country": "AE", "mcc": "4121"}`) req, _ := http.NewRequest("POST", "https://api.descriptorapi.com/v1/enrich", body) req.Header.Set("Content-Type", "application/json") req.Header.Set("Authorization", "Bearer "+os.Getenv("DESCRIPTORAPI_KEY")) resp, err := http.DefaultClient.Do(req)

const res = await fetch("https://api.descriptorapi.com/v1/enrich", { method: "POST", headers: { Authorization: `Bearer ${process.env.DESCRIPTORAPI_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({"descriptor": "POS 4521 CAREEM*RIDE DXB AE", "country": "AE", "mcc": "4121"}), }); const data = await res.json();

import os, requests res = requests.post( "https://api.descriptorapi.com/v1/enrich", headers={"Authorization": f"Bearer {os.environ['DESCRIPTORAPI_KEY']}"}, json={"descriptor": "POS 4521 CAREEM*RIDE DXB AE", "country": "AE", "mcc": "4121"}, timeout=10, ) data = res.json()

$ch = curl_init("https://api.descriptorapi.com/v1/enrich"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => '{"descriptor": "POS 4521 CAREEM*RIDE DXB AE", "country": "AE", "mcc": "4121"}', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('DESCRIPTORAPI_KEY'), 'Content-Type: application/json', ], ]); $data = json_decode(curl_exec($ch), true);

{ "descriptor": "POS 4521 CAREEM*RIDE DXB AE", "normalized": "CAREEM RIDE", "merchant": { "id": "mer_01M4TKG2681HHBYZWQE4FEQARK", "name": "Careem", "legal_name": null, "website": "https://www.careem.com", "logo_url": "https://cdn.descriptorapi.com/logos/careem-218be11e.png", "category": "transportation", "subcategory": "ride_hailing", "mcc": "4121" }, "location": { "city": "Dubai", "country": "AE" }, "processor": null, "is_subscription": false, "confidence": 0.97, "source": "cache", "verified": true }