Errors

Every Crevio error returns the same JSON envelope, so you can handle failures the same way everywhere. Read the code to branch programmatically and the errors object to surface field-level problems to users.

The error envelope

When a request fails, the body is a single error object:

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "Email can't be blank",
    "param": "email",
    "errors": { "email": ["can't be blank"] },
    "doc_url": "https://crevio.co/docs/developer/guides/errors#validation_failed"
  }
}

Field	Description
`type`	Error category — `invalid_request_error`, `validation_error`, or `api_error`.
`code`	Machine-readable code you can switch on — `parameter_missing`, `parameter_unknown`, `authentication_required`, `plan_required`, `resource_missing`, `validation_failed`, etc. Present when the error is one you can handle programmatically; unexpected server errors (`500`) have none.
`message`	Human-readable description of what went wrong.
`param`	The offending parameter. Present on parameter, plan, and validation errors that trace to one field; on a `422` with several invalid fields it names the first.
`errors`	Field-level validation errors keyed by field name. Present on `422`, and on a `402` raised by a field.
`doc_url`	Link to this page’s section for the `code`. Present when the code is documented here.

Branch on error.code, not message — messages are for humans and may change. When there is no code, branch on type and the HTTP status. Every failed response also returns an x-request-id header; include it when reporting an issue.

`parameter_missing`

HTTP 400. A required field is absent. Check param for which one.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: name",
    "param": "name"
  }
}

Fix: include the named param.

`parameter_unknown`

HTTP 400. The body is wrapped in a resource key; param names it — see Conventions.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "message": "Received unknown parameter: product. Send fields at the top level of the body, not nested under \"product\".",
    "param": "product"
  }
}

Fix: move the nested fields to the top level of the body.

`authentication_required`

HTTP 401. The token is missing, malformed, or revoked.

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "No valid API token provided."
  }
}

Fix: send Authorization: Bearer YOUR_API_TOKEN. Confirm the token wasn’t deleted in Settings → Developer, and that you didn’t leak a trailing newline into the env var.

`account_forbidden`

HTTP 403. The credential is valid, but the person behind it is not an admin of the account it acts on. Members of an account, such as customers who bought from it, cannot use its API. An API key also gets this once its creator is removed from the account or loses the admin role. Fix: authenticate as an admin of the account. For an API key, have a current admin create a new one.

`insufficient_scope`

HTTP 403. The OAuth token’s scope does not allow the request. A read_only token can only make GET requests, and no OAuth token can create API keys. Fix: send the user through authorization again and request the read_write scope. Create API keys in Settings → Developer.

`plan_required`

HTTP 402. The request was valid, but the account’s plan doesn’t include what it asks for — for example, turning off a site’s referral badge below the Business plan, or creating a site past the plan’s site limit. param names the field when one field is responsible. Nothing in the request is applied.

{
  "error": {
    "type": "invalid_request_error",
    "code": "plan_required",
    "message": "Show referral badge can only be turned off on the Business plan",
    "param": "show_referral_badge",
    "errors": { "show_referral_badge": ["can only be turned off on the Business plan"] }
  }
}

Fix: retrying won’t help. Tell the user which plan the feature needs, or drop the field and resend.

`resource_missing`

HTTP 404. The resource doesn’t exist for your account.

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such product: prod_doesnotexist"
  }
}

On POST/PATCH, a 404 almost always means a bad or nil association id in your body — not a routing problem. For example, passing a non-existent product: "prod_xxx" to POST /price_variants returns resource_missing for the product, not for the price-variants route. Double-check every prefixed id you’re sending.

Fix: verify the prefixed id (it must be a prod_…/cus_…/etc., not a raw database id) and that it belongs to your account.

`validation_failed`

HTTP 422. The request was well-formed but the data is invalid. Field errors are listed in errors.

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "Validation failed",
    "errors": {
      "email": ["can't be blank"],
      "amount": ["must be greater than 0"]
    }
  }
}

A classic 422 is publishing a product with no price variant (status: "active" on a product with zero prices). See creation order. Fix: map each key in errors to a form field and show the message inline.

`rate_limit_exceeded`

HTTP 429. You’ve exceeded the rate limit (600 requests per 60-second window, per credential).

{
  "error": {
    "type": "invalid_request_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry later."
  }
}

Fix: back off and retry, using the X-RateLimit-Reset header to time your retry. The @crevio/sdk retries with exponential backoff automatically. See Rate limits for the headers and recommended backoff strategy.

`resource_busy`

HTTP 409, type api_error. Another request was changing the same resource at the same moment, and this one was rolled back so the two could not corrupt each other. It happens when many calls write to one resource in parallel, such as attaching several files to the same experience at once.

{
  "error": {
    "type": "api_error",
    "code": "resource_busy",
    "message": "Another request was changing the same resource at the same time. Retry the request."
  }
}

Fix: retry the same request after the Retry-After header’s delay. Nothing from the failed attempt was saved. To avoid it, send writes to one resource one after another, or batch them into a single call (for example, one file_ids array instead of one call per file).

Server errors

HTTP 500, type api_error. An unexpected server error. There is no code and no doc_url — nothing about the request is yours to fix.

{
  "error": {
    "type": "api_error",
    "message": "An unexpected error occurred"
  }
}

Fix: retry idempotently. If it persists, report it with the x-request-id header from the response.

Handling errors in the SDK

The SDK throws typed errors with a statusCode you can branch on:

try {
  const product = await crevio.products.get({ id: "prod_nonexistent" });
} catch (error) {
  if (error.statusCode === 404) {
    // resource_missing — bad id
  }
}

Next steps

Conventions

Most errors trace back to a broken convention.

Quickstart

A clean, error-free first integration.

API reference

Per-endpoint required params and constraints.

Usage & billing

Check credits before calls fail for balance reasons.

Getting started

AI & agents

Core concepts

Integrations

Recipes

The error envelope

`parameter_missing`

`parameter_unknown`

`authentication_required`

`account_forbidden`

`insufficient_scope`

`plan_required`

`resource_missing`

`validation_failed`

`rate_limit_exceeded`

`resource_busy`

Server errors

Handling errors in the SDK

Next steps

Conventions

Quickstart

API reference

Usage & billing

​The error envelope

​parameter_missing

​parameter_unknown

​authentication_required

​account_forbidden

​insufficient_scope

​plan_required

​resource_missing

​validation_failed

​rate_limit_exceeded

​resource_busy

​Server errors

​Handling errors in the SDK

​Next steps

Conventions

Quickstart

API reference

Usage & billing

The error envelope

`parameter_missing`

`parameter_unknown`

`authentication_required`

`account_forbidden`

`insufficient_scope`

`plan_required`

`resource_missing`

`validation_failed`

`rate_limit_exceeded`

`resource_busy`

Server errors

Handling errors in the SDK

Next steps