Errors

Product API errors return a JSON body:

{
  "error": "Human-readable message",
  "code": "MACHINE_CODE"
}

code is present for domain errors. Generic HTTP errors may omit it.

Status codes

Status	Meaning
`400`	Invalid request (validation, disabled market)
`401`	Missing or invalid API key
`402`	Insufficient credits
`404`	Resource not found
`409`	Conflict (e.g. duplicate active watch)
`500`	Internal server error
`503`	Upstream or parse failure — retry with backoff

`code`	Typical status	Client message
`VALIDATION`	400	Invalid request
`NOT_FOUND`	404	Item not found
`CONFLICT`	409	Request conflict
`INSUFFICIENT_CREDITS`	402	Insufficient credits
`UNAVAILABLE`, `PARSE`, `NETWORK`, …	503	Item temporarily unavailable

X endpoints can return definitive content-state outcomes. These are safe to expose to end users — they are not platform or session errors.

GET /v1/x/tweets and POST /v1/x/tweets/lookup return HTTP 200 with a partial-success envelope:

{
  "meta": { "requested": 2, "found": 1 },
  "data": [ { "...": "tweet" } ],
  "errors": [ { "id": "123", "code": "TWEET_NOT_FOUND" } ]
}

Per-ID availability codes:

`code`	Meaning
`TWEET_NOT_FOUND`	Tweet does not exist or is unavailable
`TWEET_PROTECTED`	Tweet is from a protected account
`USER_SUSPENDED`	Author account is suspended

Credits are charged per the tweet lookup rate (1 base + 1 per found tweet).

Profile and XUser-keyed endpoints (/v1/x/users/:ref, timelines, followers, etc.) return HTTP 404 with:

Credits are still charged for definitive 404s — Nephia resolved the profile state.

Every response includes X-Request-Id for support correlation.