Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.arcmira.com/llms.txt

Use this file to discover all available pages before exploring further.

Arcmira returns errors in a stable JSON envelope so client logic can switch on error.code without parsing strings.

​
Envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_query",
    "message": "Required parameter `q` is missing.",
    "param": "q",
    "doc_url": "https://docs.arcmira.com/errors#invalid_query",
    "request_id": "req_8677e87a-3aeb-4403-a449-9d6ab8a1898b"
  }
}
FieldDescription
typeHigh-level category. Maps roughly to HTTP class.
codeMachine-stable error identifier. Switch on this.
messageHuman-readable explanation. Safe to surface in dev consoles.
paramWhen present, identifies the offending query/body parameter.
doc_urlDeep link into these docs.
request_idSame value as the X-Request-Id response header.

​
Request IDs

Every response — successful or not — carries an X-Request-Id header. The same value lives in error.request_id when errors occur. When contacting support at hi@arcmira.com, always include the request ID, the endpoint, and the timestamp. It’s the fastest path to a fix.

​
Status codes

HTTPerror.typeCommon error.code values
400invalid_request_errorinvalid_query, invalid_body, appearances_person_only, invalid_feedback_request
401authentication_errorinvalid_api_key
402quota_exceededquota_exceeded
403permission_errorapi_not_enabled, insufficient_scope, recommendations_not_enabled
404not_foundentity_not_found, channel_not_found, recommendation_not_found, not_found
409conflict_erroridempotency_conflict
429rate_limit_errorrate_limit_exceeded
500server_errorserver_error

​
Error code reference

​
invalid_query / invalid_body

The request failed Zod 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 endpoint or set is_appearance=true for a non-person entity. Only person entities have appearances. Use /v1/mentions or /v1/entities/{id}/mentions instead. See Appearances vs. mentions.

​
invalid_api_key

The key is missing, malformed, disabled, expired, or has been revoked. Mint a new one in Settings → 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 will tell you which scope is needed (e.g. watchlists:write, trackers:write, recommendations:read, recommendations:write). For commercial scopes, the key also needs to be on a Pro+ plan — if it isn’t, you’ll see recommendations_not_enabled first. See Scopes.

​
recommendations_not_enabled

You called a commercial intelligence route (/v1/recommendations, /v1/channels/{id}/sponsors, /v1/mentions?details=full, POST /v1/feedback, or any recommendations_summary block) on a key whose tier doesn’t include the commercial surface. The tier-level gate (recommendations_api_enabled) is independent of scopes — even a key with recommendations:read will 403 here if the plan is below Pro+. Fix: upgrade to Pro+ (pro_plus, ultra, teams, or 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 (query param or JSON body), empty query object, malformed ?query= URL-encoded JSON, or a correction id that doesn’t match the com_* / ent_* pattern for the type. See Feedback for the request shape.

​
quota_exceeded

Your monthly row pool is exhausted and on-demand spending is disabled. Either enable on-demand in Settings → Billing or wait for the next billing period.

​
entity_not_found

The entity ID or name didn’t resolve. For lookups, try a different type, broader name, or use /v1/search or /v1/entities/search first.

​
channel_not_found

The channel ID passed to /v1/channels/{id}/sponsors has no media in the index. Verify the YouTube channel ID (it should be the UC... form, not a slug).

​
recommendation_not_found

A com_* ID referenced in a feedback correction doesn’t exist (or never did). Re-pull the recommendation row that produced the ID and confirm.

​
idempotency_conflict

You reused an Idempotency-Key with a different request body. See Idempotency for the resolution.

​
rate_limit_exceeded

You exceeded per-minute throttle. Honor Retry-After. See Rate limits.

​
server_error

An unexpected server-side issue. Retry with exponential backoff. If it persists, send us the X-Request-Id.