Errors

Every error response uses the same envelope:

{
  "error": {
    "code": "company_not_found",
    "message": "company not found",
    "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

• code — a stable, machine-readable identifier. Match against this in your retry and alerting logic, not the human-readable message.
• message — a description suitable for logs or developer-facing error surfaces. Wording may change between releases.
• request_id — a UUID identifying the request. Echo it back to Sarucci support when filing a bug.

Every response (success or error) also carries the same value in an X-Request-Id header, so you can correlate logs even when no body is returned (e.g. a 504 from a load balancer). If you send your own X-Request-Id (a valid UUID) on the request, the API echoes it back.

HTTP status codes

Status	Meaning	Typical cause
200	OK	Success
201	Created	Resource created (e.g. a company)
401	Unauthorized	Missing, malformed, expired, or invalid bearer token
403	Forbidden	Token type cannot use this endpoint
404	Not found	Unknown/unowned company_id, or no run at the requested offset
409	Conflict	State changed under you (e.g. the model id you approved is stale)
422	Unprocessable entity	Request body/params failed validation
500	Server error	Transient; retry with backoff

Error codes

A non-exhaustive list — the full set is documented per-endpoint in the API Reference.

Code	When it fires
missing_bearer	No Authorization: Bearer header was sent
invalid_token	The bearer token is malformed or missing required claims
invalid_credentials	Token (or the keys behind it) is invalid or expired
partner_token_required	A non-partner token was used on a partner endpoint
validation_error	Request body or query params failed schema validation; see message
company_not_found	The company_id is unknown or not mapped to your partner account
no_run_at_offset	No persisted V2 run exists at the requested runs_ago offset
no_trained_artifact	V2 training/approval requested but no trained artifact exists
model_id_stale	The model_id you tried to approve is no longer the latest artifact
internal_error	Unhandled server-side failure; safe to retry

Recommended client behavior

• 4xx — do not retry (other than re-exchanging a token on a 401 and retrying once). The request will keep failing until the input or state changes.
• 5xx — retry with exponential backoff (suggested: 0.5s, 1s, 2s, 4s, then give up).
• Always log request_id alongside your own correlation IDs.