Errors

Error envelope format and validation codes returned by the API.

All failures return a consistent error envelope:

{
  "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:

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

idempotency_key_reuse

An Idempotency-Key was used for a previous request with a different body. Returned as 409 conflict.

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

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.

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.