API Reference

Every Omkar Cloud API works the same way: the same error codes, one usage endpoint and the same response headers. This page covers what is common to all of them. The endpoints and parameters of each API are in its playground.

Errors and status codes
Check your usage
Usage headers

Errors and status codes

Every error from the API gateway is JSON with a stable code and a human-readable message. Branch on code, never on the message: messages may be reworded, codes never are. Some errors carry extra fields, listed below.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Requests-Limit: 100000
X-RateLimit-Requests-Remaining: 0
X-RateLimit-Requests-Reset: 1793872800

{
  "code": "quota_exceeded",
  "message": "You have used all 100000 requests of your monthly limit. Upgrade your plan at https://www.omkar.cloud/tools/amazon-scraper/pricing or wait until it resets on 5 November, 2026.",
  "requests_limit": 100000,
  "requests_used": 100000,
  "renews_at": "2026-11-05T10:00:00Z"
}

code	HTTP	Meaning	What to do
`missing_api_key`	401	No API-Key header on the request.	Send the header. Get your key on the My API Key page.
`invalid_api_key`	401	The key does not belong to any account (regenerated or mistyped).	Copy the current key from My API Key.
`account_suspended`	403	The account that owns the key was suspended for violating the terms of service.	If you believe this is a mistake, write to happy.to.help@omkar.cloud.
`quota_exceeded`	429	Your plan's monthly requests are used up. The body carries requests_limit, requests_used and renews_at.	Upgrade the plan or wait until renews_at. Retrying sooner will not help.
`rate_limited`	429	Too many requests per second from your key on this API: 5 per second per key per API, 2 per second on browser-backed APIs. Also for more than 120 calls per minute to /account/usage. The body carries retry_after_seconds.	Wait for the number of seconds in the Retry-After header, then retry. Limits are per API, so calls to another API you subscribe to are not affected.
`subscription_expired`	402	Your paid subscription ended (expired_at in the body).	Renew on the API's Pricing tab.
`subscription_pending`	402	Payment is still being confirmed.	Wait a few minutes, or contact support.
`subscription_cancelled`	402	Your free plan was cancelled and its period has ended.	Reactivate it on the API's Pricing tab.
`plan_required`	402	This API has no free plan and you have no subscription to it.	Subscribe on the API's Pricing tab.
`activation_required`	402	The free plan must be activated on the website first (the message says why).	Open the API's Pricing tab and activate the free plan.
`unknown_api`	404	No API lives at this hostname.	Check the host against the API's playground URL.
`not_found`	404	The path does not exist on this API (for example an unknown /account/... path).	Check the endpoint list in the playground.
`access_denied`	4xx	A rejection without a more specific code.	Read the message, then contact support if it is unclear.
`upstream_unavailable`	502	The scraper behind this API did not answer.	Retry with backoff. Not charged.
`service_unavailable`	503	The API key check itself is down.	Retry in a few seconds. Not charged.

Responses from the scraper itself (a bad parameter, a page that does not exist on the source site) keep their own status and body. Treat any 2xx as success, 4xx as something to fix on your side (or a plan to change), and 5xx as safe to retry.

Example: handling errors

import time
import requests

response = requests.get(
    "https://amazon-scraper.omkar.cloud/search",
    params={"query": "headphones"},
    headers={"API-Key": "YOUR_API_KEY"},
)

if response.ok:
    data = response.json()
else:
    error = response.json()
    if error["code"] == "quota_exceeded":
        pause_until(error["renews_at"])          # or upgrade the plan
    elif error["code"] == "rate_limited":
        time.sleep(int(response.headers.get("Retry-After", "60")))
    elif response.status_code >= 500:
        retry_later()                            # our side; safe to retry
    else:
        log(error["code"], error["message"])

Check your usage

GET /account/usage on any API host returns your plan and usage for that API. It is free: it never consumes a request, so you can poll it before dispatching a batch. It is limited to 120 calls per minute per key.

curl "https://amazon-scraper.omkar.cloud/account/usage" \
  -H "API-Key: YOUR_API_KEY"

{
  "api": "amazon-scraper",
  "plan": "Grow",
  "billing_cycle": "monthly",
  "status": "active",
  "requests_limit": 100000,
  "requests_used": 12345,
  "requests_remaining": 87655,
  "renews_at": "2026-11-05T10:00:00Z"
}

Example: pause before the quota runs out

import requests

usage = requests.get(
    "https://amazon-scraper.omkar.cloud/account/usage",
    headers={"API-Key": "YOUR_API_KEY"},
).json()

if usage["requests_remaining"] < 1000:
    print(f"Only {usage['requests_remaining']} requests left until {usage['renews_at']}")

Usage headers

Every response that passed the key check carries your usage, so a pipeline can watch its quota without extra calls. They are present on successful responses, on upstream errors and on the quota_exceeded error.

Header	Meaning
`X-RateLimit-Requests-Limit`	Requests included in your plan per billing period.
`X-RateLimit-Requests-Remaining`	Requests left in this period, after the one you just made.
`X-RateLimit-Requests-Reset`	When the counter resets, as a Unix timestamp in seconds (UTC). Same moment as renews_at.

HTTP/1.1 200 OK
X-RateLimit-Requests-Limit: 100000
X-RateLimit-Requests-Remaining: 87654
X-RateLimit-Requests-Reset: 1793872800

Only successful data responses (HTTP 200) consume a request. Errors from us, blocked requests and upstream failures are free.

Your subscriptions and their usage are also on the Subscriptions page. Questions? Chat with us live.