Errors

Skoup uses conventional HTTP status codes: 2xx means success, 4xx means the request cannot be fulfilled as sent, 5xx means something went wrong on our side.

Every error response has the same shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "The title field is required.",
    "param": "title",
    "doc_url": "https://docs.skoup.ai/en/errors#parameter_invalid",
    "request_id": "req_7Hq2mXbN4kLp9sRt3vYw1Z"
  }
}

Types

Codes

authentication_required

401 — No Authorization: Bearer … header was sent. Every request must carry an API key.

invalid_api_key

401 — The key does not exist or is malformed. Check that you copied it entirely, including the skoup_live_ or skoup_test_ prefix.

api_key_revoked

401 — The key was revoked in the dashboard. Create a new key; revoked keys never come back.

workspace_billing_blocked

402 — The workspace is blocked for billing: its trial ended without a subscription, an invoice is still unpaid 15 days after the payment failed, or its subscription ended. Every call is refused until an owner settles it from Plan & billing in the dashboard; nothing is lost meanwhile.

plan_feature_unavailable

403 — The endpoint belongs to a feature the workspace’s plan does not include (for instance the AI traffic from GA4 or the visibility ↔ revenue correlation, from the Growth plan). The message names the plan that includes it. An owner can upgrade from Plan & billing in the dashboard; nothing already measured is lost. Test mode keys reach every feature.

capability_unavailable

403 — The endpoint belongs to a module the brand’s vertical does not have: for instance the attributed orders, the revenue correlation or the write-backs of a brand that sells software or runs a physical establishment rather than products. Read the brand’s vertical on GET /v1/brands/{id} to know which modules apply. Nothing to fix on the key or the plan: the module does not exist for this brand.

insufficient_scope

403 — The key is valid but lacks the scope required by this endpoint (for instance tasks:write for POST …/tasks). The message names the missing scope. See scopes.

resource_missing

404 — No object matches this ID, the ID has the wrong prefix, or the key is restricted to other brands.

parameter_invalid

422 — A parameter is missing or invalid. param names it and message explains why.

resource_read_only

422 — The object cannot be modified through the API. Products synchronized from a store (Shopify, feed…) are read-only in Skoup: the store is the source of truth, fix them there.

quota_exceeded

422 — A quota of your plan is reached — for example the number of active queries or of alert verifications per day. param names the quota; the matching Skoup-Quota-* header tells when it frees up.

invalid_transition

422 — The requested state change is not allowed from the object’s current state. Tasks, for instance, move one column at a time across the board.

idempotency_key_reused

422 — The Idempotency-Key was already used with a different request body. See Idempotency.

rate_limit_exceeded

429 — Too many requests. Wait for the number of seconds given by the Retry-After header. See Rate limits.

api_error

500 — An unexpected error on Skoup’s side. These are rare and monitored; retrying with exponential backoff is safe for GET requests and for writes sent with an Idempotency-Key.