Errors

SellTraces-owned JSON routes generally return an error field with an HTTP status code. Better Auth delegated routes may return provider-owned shapes. For request and response schemas on a specific operation, use the generated pages under API Reference.

Common errors

HTTP status	Error	Meaning
`400`	`invalid_json`	Request body was not valid JSON
`400`	`invalid_body`	Request JSON did not match the route schema
`401`	`unauthorized`	No valid session cookie or bearer token
`404`	`not_found`	Requested user-owned resource was not found for this user
`409`	`already_sold`	A sold trace cannot be included or excluded anymore
`409`	`access_denied`	Device code was already consumed or denied
`410`	`expired_token`	Device code expired
`415`	`unsupported_content_type`	Ingest only accepts JSON request bodies
`500`	`enqueue_failed`	Upload storage or job enqueue failed
`502`	`blob_unavailable`	A derived trace blob could not be fetched
`503`	`device_login_unavailable`	Device-login backing auth service is unavailable

Error envelope

Application-owned API routes usually return:

{
  "ok": false,
  "error": "unauthorized"
}

Some legacy pre-auth routes return:

{
  "error": "invalid_body"
}

Validation issues

POST /api/ingest can include Zod validation issues for malformed JSON uploads:

{
  "ok": false,
  "error": "invalid_body",
  "issues": []
}

Retry guidance

Retry 202 device polls after the returned interval.
Do not retry 400 schema errors without changing the request.
Treat 409 already_sold as final for trace eligibility changes.
Retry transient 500, 502, and 503 only with backoff.

API guides

Endpoints

Errors

Errors

Common errors

Error envelope

Validation issues

Retry guidance

​Errors

​Common errors

​Error envelope

​Validation issues

​Retry guidance

Errors

Common errors

Error envelope

Validation issues

Retry guidance