Error Code Reference

When the banner or your own code calls the Arqam360 API, errors come back as an HTTP status with a JSON body whose error field names the problem. Here are the ones you are most likely to meet and what to do about each.

API key errors

• 401 "API key required" — no key was sent. Send it in the X-API-Key header or as Authorization: Bearer YOUR_API_KEY. On a website, check that the script tag carries data-key="YOUR_API_KEY".
• 401 "Invalid API key" — the key doesn't match an active key on your account. It may have a typo, or it was revoked or regenerated. Copy the current key from your dashboard.
• 401 "API key expired" — the key has passed its expiry date. Create a new one.
• 403 "Secret key required" (code API_KEY_SCOPE_REQUIRED) — a public widget key was sent where a secret Site Token (starting ciq_sk_) is needed, for example the WordPress plugin's dashboard.
• 403 "Subscription inactive" or "Trial expired" — returned by paid features when your trial or subscription has lapsed. Recording consent and loading the banner keep working either way; choose a plan to restore the rest.

Request and domain errors

• 400 "Missing required fields: consent, domain" — a consent record must include both.
• 400 "Invalid consent field" — consent accepts only true or false for necessary, analytics, marketing, functional and preferences.
• 400 "Invalid domain format" — the domain must be text of 256 characters or fewer.
• 403 "Domain not registered" — the site sending consent isn't one of your account's domains. Add it under Consent → Domains; the www and bare versions of a domain count as the same site.
• 403 "API key bundleId does not match the request domain" — a mobile app key was used with a different app's bundle ID.

Rate limits (429)

A 429 Too Many Requests response means a limit was reached. Consent recording is limited to 100 requests per minute from a single IP address, and to a number of requests per 15 minutes for your account that depends on your plan: 500 on the free plan, 2,000 on Pro and 50,000 on Managed and Agency. The API as a whole also allows 1,500 requests per 15 minutes per IP address. Because each visitor's banner calls from their own IP address, the per-IP limits mostly matter for server-side integrations. Responses on these routes include RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, and a 429 also carries Retry-After, in seconds.