Error
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"invalid_request_error",
"authentication_error",
"permission_error",
"quota_exceeded",
"rate_limit_error",
"not_found",
"conflict_error",
"server_error"
],
"description": "The error class. It fixes the HTTP status: invalid_request_error 400, authentication_error 401, quota_exceeded 402, permission_error 403, not_found 404, conflict_error 409, rate_limit_error 429, server_error 500. Switch on it for retry and gate handling."
},
"code": {
"type": "string",
"description": "The specific condition, stable and snake_case; doc_url anchors on it. x-arcmira-codes on this schema lists every code with its type, gate and meaning. The list is open: new codes may appear inside an existing type, so switch on type and gate first."
},
"reason": {
"type": "string",
"enum": [
"no_credential",
"invalid",
"revoked"
],
"description": "Only on invalid_api_key. no_credential: nothing was sent. invalid: a credential was sent and is unknown or malformed. revoked: the key exists and is no longer usable."
},
"message": {
"type": "string",
"description": "One plain line. Names the fix or the unlock."
},
"param": {
"type": "string",
"description": "The query or body parameter the gate refused, when one did."
},
"gate": {
"type": "string",
"enum": [
"rows",
"key",
"plan",
"freshness",
"exposure_law",
"rate",
"pagination"
],
"description": "Which boundary refused. Present on every gate error; switch on it without parsing the message."
},
"resource": {
"$ref": "#/components/schemas/ErrorResource"
},
"unlock": {
"type": "object",
"properties": {
"tier": {
"type": "string",
"description": "The plan that lifts the gate."
},
"url": {
"type": "string",
"description": "Absolute upgrade or sign-up URL carrying its ?src= attribution. Use it verbatim."
},
"offer": {
"type": "null",
"description": "Reserved for the agent-discount offer. Always null today."
},
"action": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "What the call does. send_signup_code sends a verification code to an address for an account key."
},
"method": {
"type": "string",
"description": "HTTP method to use."
},
"url": {
"type": "string",
"description": "Absolute endpoint carrying its ?src= attribution. Call it verbatim."
}
},
"required": [
"kind",
"method",
"url"
],
"description": "The request that lifts the gate with no human, present when the caller can fix this itself. A key gate carries the signup send here; a plan or quota gate has no action and its url is a page a person opens."
}
},
"required": [
"tier",
"url",
"offer"
],
"description": "How to lift the gate. Present when the gate has an unlock."
},
"retry_after_seconds": {
"type": "integer",
"description": "Present on rate gates. Mirrors the Retry-After header."
},
"details": {
"type": "object",
"properties": {
"quote": {
"$ref": "#/components/schemas/RefusedQuote"
},
"limit": {
"$ref": "#/components/schemas/Limit"
},
"url": {
"type": "string",
"description": "On terms_acceptance_required: the page where the person accepts the updated Terms of Service. On terms_updated: the Terms of Service page."
}
},
"description": "Machine data the refusal carries for you to act on. Present only on the codes that name a field here."
},
"doc_url": {
"type": "string"
},
"request_id": {
"type": "string"
}
},
"required": [
"type",
"code",
"message",
"doc_url",
"request_id"
]
}
},
"required": [
"error"
],
"x-arcmira-codes": [
{
"code": "alert_not_found",
"type": "not_found",
"description": "A referenced alert does not exist or belongs to another account."
},
{
"code": "api_not_enabled",
"type": "permission_error",
"gate": "plan",
"description": "The plan does not include API access. unlock.url names the plan that does."
},
{
"code": "appearances_person_only",
"type": "invalid_request_error",
"description": "Appearance filtering applies to person entities only."
},
{
"code": "channel_not_found",
"type": "not_found",
"description": "No channel matches the id or slug."
},
{
"code": "email_verification_required",
"type": "permission_error",
"description": "Verify the account email before adding recipients."
},
{
"code": "entity_not_found",
"type": "not_found",
"description": "No entity matches the id, slug, or name."
},
{
"code": "fair_use_cap",
"type": "quota_exceeded",
"description": "A fair-use cap on the plan's credits is reached for this use this month, and the account has no granted or on-demand credits to use instead. Nothing was charged. details.limit carries the cap and what is used. An admin turns on on-demand usage or raises its budget, or the cap resets with the month."
},
{
"code": "feature_not_available",
"type": "permission_error",
"gate": "plan",
"description": "The plan does not include this feature. unlock.url names the plan that does."
},
{
"code": "feedback_not_found",
"type": "not_found",
"description": "No feedback submission with this id for this account."
},
{
"code": "filter_requires_paid",
"type": "permission_error",
"gate": "plan",
"description": "The parameter in param needs a paid plan; omit it for the free answer."
},
{
"code": "forbidden",
"type": "permission_error",
"description": "The caller may not perform this operation on this resource."
},
{
"code": "freshness_requires_paid",
"type": "permission_error",
"gate": "freshness",
"description": "The date window starts after results on this plan stop. details.limit carries delay_days and served_through; move the window to served_through or earlier, or open unlock.url for the plan that reads newer media."
},
{
"code": "id_required",
"type": "invalid_request_error",
"description": "A filter in param received a name where it takes an id (ent_{n} or UC...). Resolve the name first with GET /v1/entities/resolve and pass best.id or best.youtube_channel_id."
},
{
"code": "idempotency_conflict",
"type": "conflict_error",
"description": "The Idempotency-Key was sent before with a different request body. Send a new key for a new request."
},
{
"code": "idempotency_result_expired",
"type": "conflict_error",
"description": "The original one-time signing secret is no longer valid. Use a new request key for a new rotation."
},
{
"code": "insufficient_scope",
"type": "permission_error",
"gate": "key",
"description": "The key lacks the scope this route needs."
},
{
"code": "invalid_api_key",
"type": "authentication_error",
"gate": "key",
"description": "No usable credential. reason says whether none was sent, it is unknown, or it was revoked."
},
{
"code": "invalid_body",
"type": "invalid_request_error",
"description": "The JSON body failed validation; message names the field."
},
{
"code": "invalid_cursor",
"type": "invalid_request_error",
"description": "The continuation is invalid, expired, or belongs to another query. Restart without cursor."
},
{
"code": "invalid_email_recipients",
"type": "invalid_request_error",
"description": "Email recipients failed validation."
},
{
"code": "invalid_feedback_request",
"type": "invalid_request_error",
"description": "The feedback query or corrections do not fit the feedback type."
},
{
"code": "invalid_idempotency_key",
"type": "invalid_request_error",
"description": "Idempotency-Key must be 1 to 255 printable ASCII characters (0x21 to 0x7E). param is Idempotency-Key."
},
{
"code": "invalid_query",
"type": "invalid_request_error",
"description": "A query parameter failed validation; message names it."
},
{
"code": "invalid_slack_integration",
"type": "invalid_request_error",
"description": "Choose an active Slack integration owned by the account."
},
{
"code": "invalid_video_id",
"type": "invalid_request_error",
"description": "The video_id path segment is not an 11-character YouTube id."
},
{
"code": "job_requires_account",
"type": "authentication_error",
"gate": "key",
"description": "Transcription jobs belong to an account; sign up for a key."
},
{
"code": "member_limit",
"type": "quota_exceeded",
"gate": "rows",
"description": "The account's included credits are used up and the person the key or token acts for has reached their monthly on-demand limit in it. Nothing was charged, and there is no unlock. details.limit carries the limit and what is used, in US cents. An admin raises the limit on the Team page (https://arcmira.com/dashboard/members), or it resets with the month."
},
{
"code": "monitor_creation_unavailable",
"type": "server_error",
"description": "Monitor creation is temporarily unavailable. Retry the same request with the same key."
},
{
"code": "monitor_creation_unconfirmed",
"type": "server_error",
"description": "Monitor creation could not be confirmed. Retry the same request with the same key."
},
{
"code": "monitor_not_found",
"type": "not_found",
"description": "No monitor with this id on the account."
},
{
"code": "not_found",
"type": "not_found",
"description": "No route or resource at this path."
},
{
"code": "on_demand_paused",
"type": "quota_exceeded",
"gate": "rows",
"description": "The account's included credits are used up and its on-demand usage is paused, because a payment for an on-demand invoice was declined. Nothing was charged, and there is no unlock. On-demand resumes once the invoice is paid. An admin updates the card on the Billing & Invoices page (https://arcmira.com/dashboard/billing), which retries the payment."
},
{
"code": "owner_only",
"type": "permission_error",
"description": "Only an admin of the account may do this. Everyone in a team can create, edit, pause, delete and restore monitors."
},
{
"code": "owner_plan_required",
"type": "permission_error",
"description": "A team account follows its owner's plan, which does not include this. An admin can upgrade; a member's own plan does not apply."
},
{
"code": "pagination_gated",
"type": "permission_error",
"gate": "pagination",
"description": "Results past the free window need a paid plan."
},
{
"code": "paid_plan_required",
"type": "permission_error",
"description": "The operation needs a paid plan. unlock.url names the plan that does."
},
{
"code": "premium_transcript_requested",
"type": "permission_error",
"gate": "exposure_law",
"description": "Premium transcript text needs a plan with Premium transcripts."
},
{
"code": "quota_exceeded",
"type": "quota_exceeded",
"gate": "rows",
"description": "The read needs more credits than the plan, then the on-demand budget, have left. Nothing was charged. details.limit carries the plan credits or the on-demand budget the read met, with what is used and when it resets. unlock.url upgrades the plan or raises the budget."
},
{
"code": "rate_limited",
"type": "rate_limit_error",
"gate": "rate",
"description": "Too many requests in the window. Retry-After carries the wait."
},
{
"code": "recipient_upgrade_required",
"type": "permission_error",
"description": "The requested email recipient count exceeds the plan allowance."
},
{
"code": "recommendations_not_enabled",
"type": "permission_error",
"gate": "plan",
"description": "Commercial data needs a Pro+ plan."
},
{
"code": "resource_conflict",
"type": "conflict_error",
"description": "The operation conflicts with existing resource state."
},
{
"code": "scope_too_broad",
"type": "invalid_request_error",
"description": "The requested exact video scope exceeds the search filename cap; narrow by channel or date."
},
{
"code": "search_unavailable",
"type": "server_error",
"description": "Transcript search is unavailable (HTTP 503). Retry-After carries the wait."
},
{
"code": "server_error",
"type": "server_error",
"description": "Unexpected failure. Retry with backoff and quote request_id if it persists."
},
{
"code": "signup_code_invalid",
"type": "invalid_request_error",
"description": "The signup code is wrong, expired, or spent; message names the attempts left."
},
{
"code": "signup_send_limited",
"type": "rate_limit_error",
"description": "Verification code sends hit a per-address, per-IP, or per-client cap. Retry-After carries the wait."
},
{
"code": "spend_limit_exceeded",
"type": "quota_exceeded",
"description": "The request would take on-demand usage past the account's on-demand budget this month. Nothing was charged. details.limit carries the budget and what is used. Raise the budget on the Spending page or wait for the month to reset; then read again, or send a POST /v1/transcriptions request again with a new Idempotency-Key."
},
{
"code": "team_id_retired",
"type": "invalid_request_error",
"description": "team_id is retired: a monitor belongs to the account the key acts in. Omit team_id or send null."
},
{
"code": "terms_acceptance_required",
"type": "permission_error",
"description": "The person the key or token acts for has not accepted the updated Terms of Service. details.url is the page where they accept; the key or token works again as soon as they do."
},
{
"code": "terms_updated",
"type": "permission_error",
"description": "The Terms of Service changed since the person the key or token acts for last accepted them. This call was not run. Continuing to use the API accepts the updated terms, so the same call succeeds when sent again. details.url is the terms page. Sent once per person."
},
{
"code": "tracker_create_retired",
"type": "invalid_request_error",
"description": "POST /v1/trackers is retired (HTTP 410): a tracker lives inside a monitor. Follow an entity id or an exact name with POST /v1/monitors/{id}/entities, which creates the tracker in that monitor."
},
{
"code": "tracker_delivery_retired",
"type": "invalid_request_error",
"description": "Trackers have no delivery of their own: a tracker alerts through its monitor. Omit notify_email, notify_webhook, notify_slack, webhook_url, slack_channel_id and slack_integration_id, or send the value that means the monitor's delivery (true for notify_email, false or null for the rest), and set delivery with PATCH /v1/monitors/{id}. param names the field."
},
{
"code": "tracker_not_found",
"type": "not_found",
"description": "No tracker with this id on the account."
},
{
"code": "transcript_fetching",
"type": "server_error",
"description": "The caption track is being fetched, or the transcript translated, now (HTTP 503). Retry-After carries the wait; nothing was charged."
},
{
"code": "transcript_requires_account",
"type": "authentication_error",
"gate": "key",
"description": "Full transcripts need an account key; unlock.action sends a signup code."
},
{
"code": "transcript_unavailable",
"type": "not_found",
"description": "The video has no transcript in the requested lane or language; languages lists what exists."
},
{
"code": "unknown_entity",
"type": "invalid_request_error",
"description": "An explicit entity_ids value does not resolve to a searchable entity."
},
{
"code": "webhook_not_configured",
"type": "conflict_error",
"description": "The monitor has no webhook to rotate a secret for. Set webhook_url first."
}
]
}