Errors

The HTTP status tells you what kind of failure it is; the code tells you which one. Branch on the code, never on the message text, which can change.

Error format

Endpoint errors carry an error object with a stable code and a human-readable message:

{
  "error": {
    "code": "RUN_NOT_FOUND",
    "message": "Workflow run wr_abc123xyz789 not found"
  }
}

A few errors carry a plain string instead, with no code: authentication failures, the per-key rate limit, an oversized body, malformed JSON on POST /workflow-runs/, and unexpected 500s.

{
  "error": "Invalid or inactive API key."
}

Read both forms the same way:

error = response.json().get("error")
if isinstance(error, dict):
    code, message = error["code"], error["message"]
else:
    code, message = None, error  # branch on response.status_code

Every response carries an X-Request-ID header (req_...). Quote it when you contact support; the same ID appears in your API logs.

HTTP status codes

Error codes

Every code, the status it comes with, and the endpoints that return it.