> ## Documentation Index
> Fetch the complete documentation index at: https://rubie.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error envelope format and validation codes returned by the API.

All failures return a consistent error envelope:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "message": "Request validation failed",
    "details": [
      {
        "message": "Invalid return_url",
        "field": "return_url"
      }
    ]
  }
}
```

## HTTP Status Codes

| Status | `error.type`           | Meaning                                                 |
| ------ | ---------------------- | ------------------------------------------------------- |
| `401`  | `authentication_error` | Missing, malformed, or invalid API key                  |
| `403`  | `authorization_error`  | Valid key, but no access to the requested resource      |
| `404`  | `not_found`            | Resource not found or not visible to this key's account |
| `409`  | `conflict`             | State conflict — e.g. Idempotency-Key body mismatch     |
| `422`  | `validation_error`     | Input validation failed; see `details[]`                |
| `429`  | `rate_limit_exceeded`  | Rate limit hit                                          |
| `500`  | `internal_error`       | Unexpected server error                                 |

## Validation Error Codes

The `details[].code` field provides machine-readable validation context when
present:

<AccordionGroup>
  <Accordion title="invalid_input_data">
    A request field is malformed, references an unknown resource, or fails format validation.

    **Examples:**

    * `strategy_id` is not a valid strategy ID for this account
    * `credential_id` doesn't exist or isn't accessible
    * `return_url` fails origin allowlist validation
  </Accordion>

  <Accordion title="idempotency_key_reuse">
    An `Idempotency-Key` was used for a previous request with a different body.
    Returned as `409 conflict`.
  </Accordion>
</AccordionGroup>

## Error Detail Fields

| Field     | Always present | Description                                      |
| --------- | -------------- | ------------------------------------------------ |
| `message` | Yes            | Human-readable description                       |
| `code`    | No             | Machine-readable code for programmatic handling  |
| `field`   | No             | Dot-notation path to the offending request field |

## Blueprint run terminal errors

`GET /blueprint-runs/{runId}/status` returns an `error` object when `status` is
`failed`, and `null` otherwise.

| `error.code`       | Meaning                  | Suggested UX                                    |
| ------------------ | ------------------------ | ----------------------------------------------- |
| `execution_failed` | The run did not complete | Offer retry; escalate to support if it persists |

<Note>
  Today every failed run reports `execution_failed`. More specific,
  Blueprint-defined codes will be added later without changing this shape, so
  treat `error.code` as an open string set: branch on the codes you know and
  fall back to a generic retry path for anything unrecognized.
</Note>

Status responses never include run inputs, outputs, file URLs, or any run
content, so they are safe to poll from systems handling sensitive data. The
underlying failure detail is available to your Rubie team through the run in the
Rubie dashboard.