Read API

Errors and rate limits

Every error comes back in the same JSON shape, and every response carries rate-limit headers so your client can keep itself healthy.

Error envelope

One JSON shape for every error

Branch on the `error` field in your code, and show the `message` in your logs or dev tools. Every response also carries an `X-Request-Id` header; please include it whenever you report an issue so we can find it instantly.

{
  "error": "invalid_token",
  "message": "API key is missing or invalid."
}

Status codes

Every error code, explained

Each HTTP status maps to one or more `error` codes. Use this as the reference when you're handling failures in your client.

400

invalid_request, missing_ids

Your request is missing a required field or sent an unexpected value. `missing_ids` comes specifically from `/api/public/compare-products` when you forget to pass at least one `id`. Check the `message` for details.

401

invalid_token

Your API key is missing, malformed, or unknown to us. Double-check the `Authorization` header.

403

token_paused, token_revoked, token_expired, partner_inactive, partner_not_allowed

Your key exists but cannot be used right now. The `token_*` codes mean the key itself is blocked. `partner_inactive` means the partner account the key belongs to has been disabled. `partner_not_allowed` means the key is valid but not scoped to this API.

404

not_found

No product with that ID is published on Acoustic Index. Treat this as a normal outcome in search flows.

429

rate_limit_exceeded

You've hit the rate limit. Wait the number of seconds in `Retry-After` before trying again.

500

internal_error

Something went wrong on our side. Wait a few seconds and retry. If it keeps happening, send us the `X-Request-Id`.

503

rate_limit_unavailable

Our rate-limit service is briefly unavailable. Retry after a short delay.

Rate limits

How much you can call, and what to do when you can't

Read the rate-limit headers on every response so you know exactly where you stand. The two access modes use different buckets, so you never starve one by hammering the other.

Authenticated endpoints

60 requests per minute and 1,000 per day. The limit is shared across every key you create in your account, so making more keys does not get you more capacity. Watch `RateLimit-Remaining` and `Retry-After`.

Public endpoints

120 requests per minute per IP. No daily cap and no `RateLimit-Policy` header. Great for AI agents and MCP servers that cannot carry an API key.

503 responses

A `503 rate_limit_unavailable` means our rate-limit service is briefly offline, not that you did anything wrong. Wait a few seconds and try again.