Errors

When a request fails, the API answers with an HTTP status and a JSON envelope with a stable machine-readable code. Every error uses the envelope, including validation errors, unknown paths, rate limiting and unexpected server errors. The only non-envelope failure is a 503 from /health, which returns the health report with status: "unhealthy". Branch on code. The message is for people and may change. This page lists the envelope and every code in the supported API.

The envelopeCopy Anchor Link

{
  "error": {
    "code": "RUN_LEASE_LOST",
    "message": "Run is cancelled",
    "details": {}
  }
}

@sat/api-client turns the envelope into an ApiError with status, code and message; if a body has no envelope (for example an error page from a proxy in front of the API), code is HTTP_ERROR and message is the HTTP status text.

Framework errorsCopy Anchor Link

Errors raised by the web framework itself, before or around your endpoint, use the same envelope with these codes:

A schema validation error looks like this:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "runner_id: Field required",
    "details": {
      "errors": [
        {"loc": ["body", "runner_id"], "message": "Field required", "type": "missing"}
      ]
    }
  }
}

message describes the first problem as field path: message, with the field path joined by dots and without the leading body, query or path. details.errors lists every problem, each with loc (where the bad value is: body, query or path, then the field), message and type (the validator's error type, such as missing or uuid_parsing).

Rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After) are added to a 429 only when the limiter's headers are turned on with RATELIMIT_HEADERS_ENABLED=true. They are off by default, and no SAT deployment turns them on.

HTTP status codesCopy Anchor Link

404, not 403, for non-membersCopy Anchor Link

Every company endpoint first checks that you are a member of the company in the path. If you are not, the answer is 404 NOT_FOUND with the message Company not found, exactly as if the company did not exist. Resources inside a company work the same way: a task, agent, run, approval, goal, project or routine id that belongs to another company answers 404. This keeps company ids and resource ids from being probed.

403 means you are a member but lack a role: only owner and admin can update a company (FORBIDDEN).

Error codesCopy Anchor Link

Company resourcesCopy Anchor Link

Authentication and the current userCopy Anchor Link

API keysCopy Anchor Link

Any endpointCopy Anchor Link

Handling errorsCopy Anchor Link

• Retry network errors, 429, 500 and 503 with backoff. Do not retry other 4xx answers unchanged.
• On 401, refresh the session once and retry; see Refresh on 401. With an API key, a 401 means the key is revoked, expired or was created before the owner's last password reset.
• On 404 for a company, check that the credential's owner is a member. The API cannot tell you which.
• Runners treat RUN_LEASE_LOST, RUN_FINISHED and RUN_NOT_RUNNING as "stop this run now". See Build your own runner.
• The CLI maps errors to exit codes: 3 for 401 and 403, 4 for 404, 5 for conflicts and validation errors such as ORG_CYCLE or RUN_FINISHED. See CLI.

RelatedCopy Anchor Link