Errors - ai-cmo.dev

Every error response from the v1 API (except research routes and internal metering routes) follows a consistent envelope:

{
  "error": {
    "code": "string",
    "message": "string",
    "requestId": "8 hex chars",
    "details": [{ "path": [], "code": "", "message": "" }]
  }
}

details appears only on zod validation failures (HTTP 400 invalid_request), where each issue in the validation errors maps to one details entry. requestId is an 8-character hex string that correlates server-side logs to the response. Include it when reporting issues.

Error codes

HTTP	Code	Meaning	Retryable
400	`invalid_request`	Request body failed schema validation; check `details`	No — fix the payload
400	`invalid_topup_amount`	Top-up is outside $5–$ 500 range or not whole cents	No — fix the amount
400	`invalid_scope`	API key scope is not in the allowed list	No
400	`invalid_cidr`	CIDR notation is malformed	No
400	`key_not_active`	Only active keys can be rotated	No
400	`not_a_replacement`	The key is not a replacement in a rotation	No
400	`invalid_workspace_settings`	Workspace settings update failed validation	No
400	`invalid_workspace_icon`	Icon upload or refresh failed	No
400	`invalid_signature`	Stripe webhook signature verification failed	No
401	`invalid_key`	API key is absent, revoked, pending, or expired grace	No
401	`invalid_credentials`	Email or password is wrong	Yes — with corrected credentials
403	`signup_not_allowed`	Email domain is not in the allowed list	No
403	`csrf_forbidden`	Session cookie CSRF token is missing or invalid	No
403	`ip_forbidden`	Client IP is outside the key’s `allowedCidrs`	No — check the key’s CIDR
403	`metering_forbidden`	Operation token is invalid for this operation	No
404	`workspace_not_found`	Workspace does not exist, is not accessible, or key’s bound workspace does not match	No
404	`key_not_found`	API key does not exist in the workspace	No
404	`delivery_not_found`	API key delivery record not found	No
404	`job_not_found`	Job does not exist or is not accessible	No
404	`chat_thread_not_found`	Chat thread does not exist	No
404	`recommendation_not_found`	Recommendation not found	No
409	`workspace_exists`	Workspace slug is already taken	No
409	`email_exists`	Account with this email already exists	No
409	`username_exists`	Username is already in use	No
409	`username_unavailable`	Username is reserved or taken	No
409	`job_already_running`	One running measurement per brand slot is occupied	Yes — poll and retry after completion
409	`pipeline_capacity_reached`	Worker cap (`GEO_MAX_PIPELINE_JOBS`) reached; no more jobs can start	Yes — retry after backoff
409	`insufficient_credits`	Credits are too low to start or continue an operation	No — top up credits
409	`stopped_credits`	Operation stopped mid-stream because a credit lease was refused	Yes — retry the operation
409	`metering_conflict`	Idempotency key was reused with different input, or a CAS conflict	No
409	`idempotency_conflict`	Idempotency key was already used with a different request	No
409	`invalid_state`	Resource state does not allow the requested transition	No
409	`rotation_in_progress`	Key already has a replacement pending	No
409	`delivery_expired`	10-minute delivery window has passed	No — create a new key
409	`operator_provider_not_configured`	Provider is not configured for this operator	No
409	`mock_topup_disabled`	Mock top-ups are disabled when Stripe is configured	No
409	`route_not_registered`	Route is not in the API route registry	No
409	`stale_state`	Recommendation transition CAS failed (stale `expectedVersion`)	Yes — re-fetch and retry
409	`invalid_transition`	Recommendation action is not valid from current status	No
429	`rate_limited`	Generic rate limit hit	Yes — exponential backoff
429	`research_rate_limited`	Research on-demand start limit (1/hour/workspace)	Yes — retry after the window
429	`verification_cooldown`	Verification email resend cooldown not elapsed	Yes — wait and retry
503	`auth_unavailable`	Authentication is unavailable (missing server key)	Yes — retry
503	`delivery_unavailable`	Key delivery encryption is unavailable	Yes — retry
503	`entropy_unavailable`	Unable to generate a unique API key	Yes — retry
503	`billing_unavailable`	Stripe billing is not configured	No
503	`email_delivery_unavailable`	Email delivery service is unavailable	Yes — retry
500	`internal_error`	Unexpected server error	Yes — retry

Retry strategy

Category	Codes	Strategy
Terminal	`invalid_request`, `invalid_topup_amount`, `signup_not_allowed`, `csrf_forbidden`, `ip_forbidden`, `invalid_key`, `invalid_credentials`, `workspace_not_found`, `delivery_expired`, `invalid_state`, `invalid_transition`, `idempotency_conflict`	Do not retry. Fix the request.
Safe to retry	`rate_limited`, `research_rate_limited`, `verification_cooldown`, `pipeline_capacity_reached`, `internal_error`, `auth_unavailable`, `delivery_unavailable`	Retry with exponential backoff (start at 1s, double each attempt, max 5).
Retry after resolution	`job_already_running`	Poll the run list and retry when the slot is free.
Retry with correction	`insufficient_credits`, `stopped_credits`	Top up credits, then retry.
Retry with re-fetch	`stale_state`	Re-fetch the resource to get the current version, then retry.

402 insufficient_credits body

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits. Add credits to continue.",
    "requestId": "a1b2c3d4",
    "details": [
      { "path": ["requiredMicrousd"], "code": "insufficient_credits", "message": "500000" },
      { "path": ["availableMicrousd"], "code": "insufficient_credits", "message": "100000" }
    ]
  }
}

409 stalestate body

{
  "error": {
    "code": "stale_state",
    "message": "Recommendation state version has changed",
    "requestId": "e5f6g7h8"
  }
}

​Error codes

​Retry strategy

​402 insufficient_credits body

​409 stalestate body

Error codes

Retry strategy

402 insufficient_credits body

409 stalestate body