API reference

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, so you can paste it straight from a log into a browser.

The error envelope

4xx · error

{
  "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; safe to log and show to operators.
`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. Quote it when contacting support.
`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, and every 401 carries an RFC 6750 WWW-Authenticate challenge.

400 Bad Request

Code	Title	Message
bad_request	Bad request	A required parameter is missing.
malformed_body	Malformed request body	The request body could not be parsed. Send valid JSON matching the Content-Type header.

401 Unauthorized

Code	Title	Message
unauthorized	Unauthorized	A valid bearer token is required.

403 Forbidden

Code	Title	Message
insufficient_scope	Insufficient scope	This token does not have the required scope.
forbidden	Forbidden	You are not authorized to perform this action.
live_mode_forbidden	Live mode forbidden	Live mode requires production access.
activation_forbidden	Activation forbidden	Activating a cascade requires production access. It stays a draft, which runs in test mode.
review_assigned_elsewhere	Review assigned to another user	This review is assigned to another user.

404 Not Found

Code	Title	Message
not_found	Not found	The requested resource was not found.

405 Method Not Allowed

Code	Title	Message
method_not_allowed	Method not allowed	The request could not be completed.

406 Not Acceptable

Code	Title	Message
not_acceptable	Not acceptable	The request could not be completed.
unsupported_format	Unsupported export format	Supported formats are .csv and .zip.

409 Conflict

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

422 Unprocessable Content

Code	Title	Message
unprocessable_content	Unprocessable content	The request could not be completed.
validation_failed	Validation failed	The request could not be processed.
missing_idempotency_key	Idempotency-Key header missing	Idempotency-Key header is required.
generation_failed	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	Rate limited	Rate limit exceeded. Retry later.

500 Internal Server Error

Code	Title	Message
internal_server_error	Internal server error	The request could not be completed.

501 Not Implemented

Code	Title	Message
not_implemented	Not implemented	The request could not be completed.

503 Service Unavailable

Code	Title	Message
designer_busy	Cascade designer busy	The cascade designer is busy right now. Please try again in a moment.