error.code without parsing strings.
Envelope
| Field | Description |
|---|---|
type | High-level category. Maps roughly to HTTP class. |
code | Machine-stable error identifier. Switch on this. |
message | Human-readable explanation. Safe to surface in dev consoles. |
param | Reserved: identifies the offending query/body parameter. Not currently populated; rely on message. |
doc_url | Deep link to the matching section on this page. |
request_id | Same value as the X-Request-Id response header. |
409 { error, reason, currentRevision }, 412 { error, expectedSeq }; see Transcripts for coding agents); transcript unlock and submission payment failures return a bare { error, quote } body so the refused price is machine-readable; and tier gates on delivery features (webhook/Slack on a plan without them) return a bare 403 { error, upgradeRequired: true, feature } body. These are reflected as-is in the docs and spec.
Request IDs
Every response, successful or not, carries anX-Request-Id header; the same value lives in error.request_id on failures. When contacting support, always include the request ID, the endpoint, and a timestamp. It’s the fastest path to a fix.
Status codes
| HTTP | error.type | Cause | Solution |
|---|---|---|---|
| 400 | invalid_request_error | Malformed params or body (invalid_query, invalid_body, appearances_person_only, invalid_feedback_request) | Fix the request; error.message carries the validator output |
| 401 | authentication_error | Missing/bad key (invalid_api_key) | Mint or fix the key; check the header form |
| 402 | quota_exceeded | Monthly rows exhausted, on-demand off | Enable on-demand in Settings → Billing or wait for the cycle |
| 403 | permission_error | Plan or scope gate (api_not_enabled, insufficient_scope, recommendations_not_enabled) | Upgrade the plan or re-scope the key |
| 404 | not_found | Unresolvable resource (entity_not_found, channel_not_found, alert_not_found, not_found) | Verify the ID; resolve via search/lookup first |
| 409 | conflict_error | idempotency_conflict | New logical operation, new Idempotency-Key |
| 429 | rate_limit_error | rate_limit_exceeded | Honor Retry-After; see Usage, limits & billing |
| 500 | server_error | Unexpected server-side issue | Retry with backoff; report the X-Request-Id if it persists |
Error code reference
invalid_query / invalid_body
The request failed schema validation. error.message contains the validator’s output and error.param (where available) identifies the offending field. Almost always a client-side fix.
appearances_person_only
You called an appearance surface or set is_appearance=true for a non-person entity. Only person entities have appearances; organizations, products, topics, and channels are mention-only. Use /v1/mentions or /v1/entities/{id}/mentions instead. See Search.
invalid_api_key
The key is missing, malformed, disabled, expired, revoked, or an internal (arc_int_*) key, which v1 rejects. Mint an arc_sk_* key in Dashboard → API Keys.
api_not_enabled
Your plan does not currently include API access. Upgrade your plan or contact hi@arcmira.com.
insufficient_scope
The key is valid but missing the scope required by the endpoint; the message names it (monitors:write, trackers:write, recommendations:read). For commercial scopes the key also needs a Pro+ plan; if it isn’t, you’ll see recommendations_not_enabled first. See Authentication & scopes.
recommendations_not_enabled
You called a commercial intelligence surface (/v1/recommendations, /v1/channels/{id}/sponsors, /v1/mentions?details=full, commercial Community Review, or a recommendations_summary block) on a tier below Pro+. The tier gate (recommendations_api_enabled on /v1/me) is independent of scopes: even a key with recommendations:read gets this on a lower plan.
Fix: upgrade to Pro+ (pro_plus, ultra, teams, enterprise) or use the non-commercial alternative (e.g. /v1/mentions without details=full).
invalid_feedback_request
POST /v1/feedback rejected the submission shape. Common causes: missing type, empty query, malformed ?query= URL-encoded JSON, or a malformed com_* / ent_* ID in a correction. See Community Review for the request shape.
quota_exceeded
Your monthly row pool is exhausted and on-demand spending is disabled. Enable on-demand in Settings → Billing or wait for the next billing period. A different 402 exists on transcript unlock/submission when the pool cannot cover that specific purchase: it returns a bare { error, quote } body (no envelope) so the refused price is machine-readable.
entity_not_found
The entity ID or name didn’t resolve. Try a different type, a broader name, or /v1/entities/search first.
monitor_not_found / tracker_not_found
The monitor or tracker ID doesn’t exist or doesn’t belong to your account. List your resources with GET /v1/monitors / GET /v1/trackers and re-check the ID.
invalid_video_id
video_id must be an 11-character YouTube video ID (the dQw4w9WgXcQ form), not a URL or a slug. Extract it from the watch URL before calling transcript or correction endpoints.
not_found
The path doesn’t match any v1 endpoint. Check the method and path against the API reference.
channel_not_found
The channel ID passed to /v1/channels/{id}/sponsors has no media in the index. Verify the YouTube channel ID (the UC... form, not a slug).
alert_not_found
A monitor_alert feedback submission referenced an alert row that doesn’t exist or doesn’t belong to your account. Re-pull GET /v1/monitors/{id}/alerts and use the row id verbatim.
feedback_not_found
The feedback_id passed to GET /v1/feedback/{feedback_id} doesn’t exist or wasn’t submitted by your account. Unknown and foreign IDs are indistinguishable by design.
webhook_not_configured
You called POST /v1/monitors/{id}/webhook-secret/rotate on a monitor with no webhook configured. Enable one first with PATCH { "notifyWebhook": true, "webhookUrl": "..." }, which returns the secret once.
idempotency_conflict
You reused an Idempotency-Key with a different request body. Mint a new key for each new logical operation. See Requests & conventions.
rate_limit_exceeded
You exceeded the per-minute throttle. Honor Retry-After. See Usage, limits & billing.
server_error
An unexpected server-side issue. Retry with exponential backoff. If it persists, send us the X-Request-Id.