> ## Documentation Index
> Fetch the complete documentation index at: https://crevio.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> Crevio's error model in full — the error envelope, the type/code/message/param/errors fields, and how to debug every HTTP status.
**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:
```json theme={null}
{
"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`, `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. The most common cause is **wrapping your body** (`{"product": {...}}`) so the real fields never reach the server — see [Conventions](/developer/guides/conventions#parameters-are-unwrapped-top-level).
```json theme={null}
{
"error": {
"type": "invalid_request_error",
"code": "parameter_missing",
"message": "Missing required parameter: name",
"param": "name"
}
}
```
**Fix:** send fields at the top level and include the named `param`.
## 401 — `authentication_required`
The token is missing, malformed, or revoked.
```json theme={null}
{
"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.
```json theme={null}
{
"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`.
```json theme={null}
{
"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](/developer/guides/conventions#creation-order-matters).
**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).
```json theme={null}
{
"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`](/developer/guides/sdk) retries with exponential backoff automatically. See [Rate limits](/developer/guides/rate-limits) for the headers and recommended backoff strategy.
## 500 — `api_error`
An unexpected server error.
```json theme={null}
{
"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:
```typescript theme={null}
try {
const product = await crevio.products.get({ id: "prod_nonexistent" });
} catch (error) {
if (error.statusCode === 404) {
// resource_missing — bad id
}
}
```
## Next steps
Most errors trace back to a broken convention.
A clean, error-free first integration.
Per-endpoint required params and constraints.
Check credits before calls fail for balance reasons.