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"] }
  }
}

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`, `resource_missing`, `validation_failed`, etc.
`message`	Human-readable description of what went wrong.
`param`	The offending parameter. Present on parameter and validation errors.
`errors`	Field-level validation errors keyed by field name. Present on `422`.

Branch on error.code, not message — messages are for humans and may change. Every failed response also returns an x-request-id header; include it when reporting an issue.

400 — `parameter_missing`

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.

400 — `parameter_unknown`

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.

401 — `authentication_required`

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.

404 — `resource_missing`

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.

422 — `validation_failed`

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.

429 — `rate_limit_exceeded`

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.

500 — `api_error`

An unexpected server error.

{
  "error": {
    "type": "api_error",
    "code": "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

400 — `parameter_missing`

400 — `parameter_unknown`

401 — `authentication_required`

404 — `resource_missing`

422 — `validation_failed`

429 — `rate_limit_exceeded`

500 — `api_error`

Handling errors in the SDK

Next steps

Conventions

Quickstart

API reference

Usage & billing

​The error envelope

​400 — parameter_missing

​400 — parameter_unknown

​401 — authentication_required

​404 — resource_missing

​422 — validation_failed

​429 — rate_limit_exceeded

​500 — api_error

​Handling errors in the SDK

​Next steps

Conventions

Quickstart

API reference

Usage & billing

The error envelope

400 — `parameter_missing`

400 — `parameter_unknown`

401 — `authentication_required`

404 — `resource_missing`

422 — `validation_failed`

429 — `rate_limit_exceeded`

500 — `api_error`

Handling errors in the SDK

Next steps