​
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 statusErrorMeaning
400invalid_jsonRequest body was not valid JSON
400invalid_bodyRequest JSON did not match the route schema
401unauthorizedNo valid session cookie or bearer token
404not_foundRequested user-owned resource was not found for this user
409already_soldA sold trace cannot be included or excluded anymore
409access_deniedDevice code was already consumed or denied
410expired_tokenDevice code expired
415unsupported_content_typeIngest only accepts JSON request bodies
500enqueue_failedUpload storage or job enqueue failed
502blob_unavailableA derived trace blob could not be fetched
503device_login_unavailableDevice-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.