---
title: API error codes
description: Every error code the Cascades API returns, grouped by HTTP status, with the envelope shape, causes and fixes.
canonical_url: "https://cascades.crscreditapi.com/docs/api/errors"
doc_version: "1.0.0"
last_updated: "2026-10-09T18:04:24Z"
source: config/api_error_codes.yml
---

# API error codes

Every failed request returns one JSON envelope with a stable machine-readable `code`. The `doc_url` in that envelope links to the page for its code. The envelope schema is `ErrorEnvelope` in [openapi.json](https://cascades.crscreditapi.com/openapi.json#/components/schemas/ErrorEnvelope) ([YAML](https://cascades.crscreditapi.com/openapi.yaml)).

```json
{
  "error": {
    "code": "validation_failed",
    "message": "The request could not be processed.",
    "details": [
      { "field": "execution_mode", "message": "must be test or live" }
    ],
    "request_id": "6f1c2a3e-8d4b-4c5e-9f0a-1b2c3d4e5f60",
    "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/validation_failed"
  }
}
```

| Field | Type | Meaning |
| --- | --- | --- |
| `code` | string | Stable identifier for the failure. Branch on this, never on `message`. |
| `message` | string | Human-readable summary. Wording may change. |
| `details` | array | Zero or more `{ field, message }` entries naming the parameter, filter, or scope at fault. |
| `request_id` | string | Correlation id, also sent as the `X-Request-Id` header. |
| `doc_url` | string | Link to the page for this `code` on the origin you called. |

Rate limits (`429`) also send a `Retry-After` header in seconds; every `401` carries an RFC 6750 `WWW-Authenticate` challenge.

## 400 Bad Request

| Code | Title | Message |
| --- | --- | --- |
| [`bad_request`](https://cascades.crscreditapi.com/docs/api/errors/bad_request.md) | Bad request | A required parameter is missing. |
| [`malformed_body`](https://cascades.crscreditapi.com/docs/api/errors/malformed_body.md) | Malformed request body | The request body could not be parsed. Send valid JSON matching the Content-Type header. |

## 401 Unauthorized

| Code | Title | Message |
| --- | --- | --- |
| [`unauthorized`](https://cascades.crscreditapi.com/docs/api/errors/unauthorized.md) | Unauthorized | A valid bearer token is required. |

## 403 Forbidden

| Code | Title | Message |
| --- | --- | --- |
| [`insufficient_scope`](https://cascades.crscreditapi.com/docs/api/errors/insufficient_scope.md) | Insufficient scope | This token does not have the required scope. |
| [`forbidden`](https://cascades.crscreditapi.com/docs/api/errors/forbidden.md) | Forbidden | You are not authorized to perform this action. |
| [`live_mode_forbidden`](https://cascades.crscreditapi.com/docs/api/errors/live_mode_forbidden.md) | Live mode forbidden | Live mode requires production access. |
| [`activation_forbidden`](https://cascades.crscreditapi.com/docs/api/errors/activation_forbidden.md) | Activation forbidden | Activating a cascade requires production access. It stays a draft, which runs in test mode. |
| [`review_assigned_elsewhere`](https://cascades.crscreditapi.com/docs/api/errors/review_assigned_elsewhere.md) | Review assigned to another user | This review is assigned to another user. |

## 404 Not Found

| Code | Title | Message |
| --- | --- | --- |
| [`not_found`](https://cascades.crscreditapi.com/docs/api/errors/not_found.md) | Not found | The requested resource was not found. |

## 405 Method Not Allowed

| Code | Title | Message |
| --- | --- | --- |
| [`method_not_allowed`](https://cascades.crscreditapi.com/docs/api/errors/method_not_allowed.md) | Method not allowed | The request could not be completed. |

## 406 Not Acceptable

| Code | Title | Message |
| --- | --- | --- |
| [`not_acceptable`](https://cascades.crscreditapi.com/docs/api/errors/not_acceptable.md) | Not acceptable | The request could not be completed. |
| [`unsupported_format`](https://cascades.crscreditapi.com/docs/api/errors/unsupported_format.md) | Unsupported export format | Supported formats are .csv and .zip. |

## 409 Conflict

| Code | Title | Message |
| --- | --- | --- |
| [`workflow_inactive`](https://cascades.crscreditapi.com/docs/api/errors/workflow_inactive.md) | Workflow inactive | Only active workflows can run batches through the public API. |
| [`conflict`](https://cascades.crscreditapi.com/docs/api/errors/conflict.md) | Conflict | The request could not be completed. |
| [`idempotency_conflict`](https://cascades.crscreditapi.com/docs/api/errors/idempotency_conflict.md) | Idempotency key reused | The Idempotency-Key has already been used with a different request payload. |
| [`execution_not_cancellable`](https://cascades.crscreditapi.com/docs/api/errors/execution_not_cancellable.md) | Execution not cancellable | Execution is already <status>. |
| [`review_not_pending`](https://cascades.crscreditapi.com/docs/api/errors/review_not_pending.md) | Review not pending | Execution is not awaiting human review. |
| [`review_already_decided`](https://cascades.crscreditapi.com/docs/api/errors/review_already_decided.md) | Review already decided | Review was already <approved/denied>. |
| [`batch_not_cancellable`](https://cascades.crscreditapi.com/docs/api/errors/batch_not_cancellable.md) | Batch not cancellable | Batch is in status <status> and cannot be cancelled. |
| [`batch_not_resumable`](https://cascades.crscreditapi.com/docs/api/errors/batch_not_resumable.md) | Batch not resumable | Batch is in status <status> and cannot be resumed. |
| [`batch_not_retryable`](https://cascades.crscreditapi.com/docs/api/errors/batch_not_retryable.md) | Batch has no retryable rows | Batch is in status <status> and has no retryable rows. |
| [`delivery_not_retryable`](https://cascades.crscreditapi.com/docs/api/errors/delivery_not_retryable.md) | Delivery not retryable | Delivery is in status <status> and cannot be retried. |

## 422 Unprocessable Content

| Code | Title | Message |
| --- | --- | --- |
| [`unprocessable_content`](https://cascades.crscreditapi.com/docs/api/errors/unprocessable_content.md) | Unprocessable content | The request could not be completed. |
| [`validation_failed`](https://cascades.crscreditapi.com/docs/api/errors/validation_failed.md) | Validation failed | The request could not be processed. |
| [`missing_idempotency_key`](https://cascades.crscreditapi.com/docs/api/errors/missing_idempotency_key.md) | Idempotency-Key header missing | Idempotency-Key header is required. |
| [`generation_failed`](https://cascades.crscreditapi.com/docs/api/errors/generation_failed.md) | Cascade generation failed | <designer failure, e.g. "We couldn't reach the cascade designer. Please try again."> |

## 429 Too Many Requests

| Code | Title | Message |
| --- | --- | --- |
| [`rate_limited`](https://cascades.crscreditapi.com/docs/api/errors/rate_limited.md) | Rate limited | Rate limit exceeded. Retry later. |

## 500 Internal Server Error

| Code | Title | Message |
| --- | --- | --- |
| [`internal_server_error`](https://cascades.crscreditapi.com/docs/api/errors/internal_server_error.md) | Internal server error | The request could not be completed. |

## 501 Not Implemented

| Code | Title | Message |
| --- | --- | --- |
| [`not_implemented`](https://cascades.crscreditapi.com/docs/api/errors/not_implemented.md) | Not implemented | The request could not be completed. |

## 503 Service Unavailable

| Code | Title | Message |
| --- | --- | --- |
| [`designer_busy`](https://cascades.crscreditapi.com/docs/api/errors/designer_busy.md) | Cascade designer busy | The cascade designer is busy right now. Please try again in a moment. |

## Sitemap

See the full [sitemap](https://cascades.crscreditapi.com/sitemap.md) for all pages.