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
`403`	`terms_required`	The account has not accepted the current Sell Traces Contributor Terms; nothing was stored
`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": []
}

Contributor Terms

POST /api/ingest returns 403 until the signed-in account accepts the current Sell Traces Contributor Terms. The body links to the dashboard page where the user accepts them:

{
  "ok": false,
  "error": "terms_required",
  "acceptUrl": "https://app.rebates.ai/dashboard/traces/terms"
}

Retry guidance

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