X-Autopilot

X Ads API errors: the sandbox host that no longer resolves

77 error constants, one worked example, and placeholders that never fill in. Plus the sandbox hostname in X's own docs that returns NXDOMAIN.

X-Autopilot Team··9 min read
On this page · 11 sections

The short version

  • ▸The documented sandbox hostname is dead. ads-api-sandbox.x.com returns NXDOMAIN from the system resolver, 8.8.8.8, 1.1.1.1 and Google DNS-over-HTTPS as of 15 November 2026. The legacy ads-api-sandbox.twitter.com still resolves, still answers, and its TLS certificate was issued on 13 November 2026, so the environment is alive under the old name only.
  • ▸X's Ads API error table lists 77 CAPS_CASE constants across 10 HTTP status codes. There is exactly one worked error example across all 32 pages of X's Ads API documentation index, 940 KB of markdown, and it is for INVALID_PARAMETER.
  • ▸You will not see those constants on the path you are most likely to hit. Every documented route answers an unauthenticated request with HTTP 400 and the legacy numeric body code 215, Bad Authentication data. Only an undocumented route returns the documented 401 UNAUTHORIZED_ACCESS shape.
  • ▸HTTP status does not follow the code name. ACCOUNT_NOT_FOUND and USER_NOT_FOUND return 403, while the other 23 NOT_FOUND constants return 404. Branching on status alone will route two lookup failures into your permissions path.
  • ▸A 200 is not a success on catalog writes. PUT product_catalogs/:id/products returns a per-product status enum including ERROR inside a 200 envelope, which directly contradicts the error page's rule that errors come with a non-200-series code.

Quick answer

The X Ads API documents 77 error constants and gives you one worked example of any of them. In practice the first error most integrations meet is not in that table at all: every documented route answers an unauthenticated request with HTTP 400 and {"errors":[{"message":"Bad Authentication data","code":215}]}, a numeric code from the retired v1.1 vocabulary. The documented UNAUTHORIZED_ACCESS shape only appears when you ask for a route that does not exist. And the sandbox hostname X tells you to build against, ads-api-sandbox.x.com, has no DNS record at all.

Last updated: November 2026

Everything below was probed live on 15 November 2026 against X (formerly Twitter) production and sandbox hosts. Where a claim comes from a document rather than a request, the document is linked and dated.

The sandbox host does not exist

Start here, because it will cost you an afternoon before you suspect the docs.

X's Ads API sandbox page says: "Using the sandbox is as simple as calling the appropriate hostname of ads-api-sandbox.x.com." That hostname returns NXDOMAIN.

ResolverResult for ads-api-sandbox.x.com
System resolverNXDOMAIN
Google, 8.8.8.8NXDOMAIN
Cloudflare, 1.1.1.1NXDOMAIN
Google DNS-over-HTTPSStatus 3, authoritative SOA from a.u10.twtrdns.net
Control: ads-api.x.comCNAME to wr.x.com, then an A record

Three independent recursive resolvers plus DoH, all authoritative-negative, with the production host resolving fine from the same machine at the same moment. This is not a propagation blip or a local DNS problem.

That environment itself is alive. ads-api-sandbox.twitter.com resolves via CNAME to s.twitter.com, answers on HTTPS, and presented a *.twitter.com certificate issued on 13 November 2026, two days before we checked. Someone is still renewing certificates for it. What never happened is the DNS record for the x.com name the documentation was rewritten to use.

So: point at ads-api-sandbox.twitter.com. Everything else in the sandbox guide holds, including the six endpoints that exist only there, which are the ones that let you mint an advertiser account and a fake funding instrument while your access application is pending. That workflow is the whole reason the sandbox matters, and it is covered in X Ads API campaigns.

77 constants, 10 status codes

As an inventory, the error table is genuinely useful. Here is its shape, which the page itself never summarises:

HTTPConstants
40428
40028
40312
5032
4292
500, 423, 408, 405, 4011 each

Two details worth pinning down. The 429 bucket holds both TOO_MANY_REQUESTS and TWEET_RATE_LIMIT_EXCEEDED, which have different recovery behaviour: the first is your API quota, the second is the posting limit on the promotable account. And LOCK_ACQUISITION_TIMEOUT returns 423 Locked, a status almost nothing else in X's surface area uses, which means a generic HTTP client may not have a branch for it.

It is also hand-maintained, and it shows. It is alphabetical except for three rows: LOCK_ACQUISITION_TIMEOUT sits before LINE_ITEM_APP_NOT_FOUND, and OVER_CAPACITY sits after SERVICE_UNAVAILABLE. Small thing, but it tells you the list is curated by hand rather than generated, which is consistent with the next finding.

The table is not complete

INCOMPATIBLE_LINE_ITEM is named in the Campaign Management reference, on the promoted accounts endpoint, as an HTTP 400. It is not in the 77-row table.

That is the only one we could prove by grep across all 32 pages of the Ads API documentation index, because the docs almost never name a constant outside that one page. But one proven omission in a list presented as the reference is enough to stop treating it as exhaustive. Write a default branch.

The status code does not follow the name

Twenty-five constants end in NOT_FOUND. Twenty-three of them return 404. Two do not:

  • ACCOUNT_NOT_FOUND returns 403
  • USER_NOT_FOUND returns 403

The same inconsistency runs the other way through the INVALID_* family: 18 constants start with INVALID_, 14 return 400 as you would expect, and four return 404, including INVALID_APP_ID and INVALID_IAB_CATEGORY.

There is a logic to the 403s, in that X prefers not to confirm whether an account exists to a caller who cannot see it. But it means the obvious client design, where 404 maps to "this id is wrong" and 403 maps to "ask for more permissions," sends two of the most common lookup failures down the wrong path. Switch on errors[0].code, not on the status.

The error you will actually get first

Here is what six live probes returned on 15 November 2026, all unauthenticated:

RequestHTTPBody
GET /12/accounts400code: 215, Bad Authentication data
GET /12/accounts/abcdefg/campaigns400code: 215, Bad Authentication data
GET /12/line_items/placements400code: 215, Bad Authentication data
GET /99/accounts400code: 215, Bad Authentication data
GET /12/nonexistent_route_test401UNAUTHORIZED_ACCESS with a request node
Same two shapes on ads-api-sandbox.twitter.com400 / 401Identical

Read that table again, because the pattern is backwards from what you would expect. Ask for something real without credentials and you get a numeric legacy code and a 400. Ask for something that does not exist and you get the documented CAPS_CASE constant and a 401. The documented error shape is the one you see when you ask for a route that was never implemented.

Practical consequence: code in an Ads API error body is sometimes a string and sometimes an integer. If your deserialiser types it as a string, the single most common auth failure will throw inside your error handler rather than being reported by it.

The one example in the docs is not what the API sends

Here is the error page's lone example:

{
  "errors": [
    {
      "parameter": "start_time",
      "details": "invalid date",
      "code": "INVALID_PARAMETER",
      "value": "",
      "message": "Expected time, got \"\" for start_time"
    }
  ],
  "request": { "params": { "account_id": "hkk5" } }
}

Five fields in the error object, and a request node echoing your parameters back. Now here is a real one, reported on X's developer forum on 10 November 2026 by someone hitting the synchronous stats endpoint:

{
  "errors": [
    { "code": "INVALID_PARAMETER", "message": "Expected %s, got \"%s\" for %s", "parameter": "entity" }
  ],
  "request": { "params": {} }
}

Those printf placeholders were never substituted. details and value are absent. And request.params came back empty, which breaks the one guarantee the docs make about successful and failed responses alike: that the request node echoes what you sent.

That reporter's account was on Asia/Kolkata, a half-hour UTC offset, and two other ad accounts from the same advertiser on whole-hour offsets returned 200 for the same request shape. They also established that time parsing happens before the failure, because deliberately bad windows produced a clean INVALID_TIME_WINDOW. The thread had no reply when we read it on 15 November 2026. If you sync analytics for accounts outside whole-hour offsets, test that path specifically.

A 200 is not always a success

X's error page states the rule plainly: "Error responses are served with a non-200-series HTTP code." The Catalog Management reference breaks it.

PUT product_catalogs/:product_catalog_id/products returns a per-product object carrying its own warnings array, its own errors array, and a status enum with four values: CREATE_SUCCESS, UPDATE_SUCCESS, ERROR and NO_CHANGE. A batch upsert where half the products fail validation still comes back 200 at the HTTP layer, with the failures itemised inside. Catalog feeds are exactly where this hurts, since nothing in the product feed path ever deletes on its own, a behaviour covered in X Dynamic Product Ads.

Check products_response[].status on every catalog write. The HTTP code will not tell you.

Rate limiting, and a reference that is gone

Two header families, and the docs are clear that you should prefer the second where it appears:

  • User level: x-rate-limit-limit, x-rate-limit-remaining, x-rate-limit-reset
  • Ad account level: x-account-rate-limit-limit, x-account-rate-limit-remaining, x-account-rate-limit-reset

Account-level limits are returned on GET endpoints only, so a tool syncing many advertisers from one user token gets per-account budgets for reads and shares a single global bucket for writes. The headline numbers: 450 writes per minute across all of POST, PUT and DELETE, 250 synchronous analytics calls per 15 minutes, 10,000 core entity reads per 15 minutes at the account level, 60,000 conversions, and just five per 15 minutes for global reads on GET endpoints that carry no account_id. That last one is low enough to break a naive startup routine that enumerates reference data on boot. Cache it.

Its primary link, for the rate limiting model it says the Ads API follows, points at developer.x.com/content/developer-twitter/en/docs/basics/rate-limits. It 307-redirects to developer.x.com/. The document that defines the behaviour is not reachable from the page that defers to it, the same pattern that runs through X Ads API A/B testing.

Nothing is shared with the v2 API

X Ads APIX API v2
Envelopeerrors[] plus requestFlat object
Identifiercode, CAPS_CASE or integertype, a URI
Auth failure status400401
Published inventory77 in a table61 in the OpenAPI spec

Two APIs, one vendor, zero shared field names beyond errors, and no crosswalk between the vocabularies. The v2 side has its own gap between what is documented and what ships, which we measured in X API error codes.

The bottom line

The Ads API error surface is better specified than most, and then undermined in four specific ways: a sandbox hostname with no DNS record, a constant missing from the canonical list, an auth path that returns a different vocabulary than the one documented, and a catalog endpoint that puts failures inside a 200. None of these is hard to work around once you know. All of them are invisible if you build from the page.

If you are weighing whether the Ads API is worth wiring up at all, the deadline on its auth method matters more than any of this, and X Ads API has that date. For organic posting rather than paid, X-Autopilot runs on your own Mac in your own browser session instead of calling an API, which is a different set of trade-offs rather than a safer one, and we set out what that means on the download page.

Frequently asked

Answers indexed by Google + AI assistants.

Why is ads-api-sandbox.x.com not resolving?+

Because the DNS record does not exist. Queries from the system resolver, Google at 8.8.8.8, Cloudflare at 1.1.1.1 and Google DNS-over-HTTPS all returned NXDOMAIN on 15 November 2026, with the authoritative SOA for x.com answering. The control host ads-api.x.com resolves normally to a CNAME of wr.x.com. The sandbox itself is not gone: ads-api-sandbox.twitter.com resolves, answers requests, and presented a wildcard twitter.com certificate issued on 13 November 2026. X renamed the host in its documentation without creating the record.

How many X Ads API error codes are there?+

77 in the published table, mapped across 10 HTTP status codes: 28 return 404, 28 return 400, 12 return 403, two each return 503 and 429, and one each returns 500, 423, 408, 405 and 401. At least one more exists outside the table. The Campaign Management reference names INCOMPATIBLE_LINE_ITEM as an HTTP 400 on the promoted accounts endpoint, and that constant is not in the list.

What does Bad Authentication data with code 215 mean on the Ads API?+

It means your OAuth 1.0a signature was missing or malformed and the request never reached the Ads application layer. The 215 is a numeric code from the old v1.1 vocabulary rather than one of the 77 CAPS_CASE constants, and it arrives with HTTP 400 rather than the 401 the error table assigns to UNAUTHORIZED_ACCESS. Both the production and sandbox hosts behave this way on every documented route.

Why are the placeholders in my X Ads API error message not filled in?+

It is a server-side formatting bug, not something in your request. A developer reported on 10 November 2026 that the synchronous stats endpoint returned the literal string Expected %s, got "%s" for %s with an empty request.params node, on an ad account whose timezone sits on a half-hour UTC offset. The thread has no staff reply. Treat the parameter field as the only reliable part of that body.

Do X Ads API errors look like X API v2 errors?+

No, and nothing is shared between them. v2 returns a flat object with a type URI, title and detail. The Ads API returns an errors array of objects with code and message, alongside a request node that is supposed to echo your parameters. A client written against one cannot read the other, and X publishes no crosswalk. The v2 side has its own documentation gap, covered separately.

Can I still test against the X Ads API sandbox?+

Yes, by pointing at ads-api-sandbox.twitter.com instead of the documented ads-api-sandbox.x.com. Everything else in X's sandbox guide still applies: campaigns created there are never served to users, and six endpoints exist only in that environment, covering creating and deleting advertiser accounts, account features and funding instruments. Start with POST accounts to mint a test account_id.

Sources
Related searches
x ads api error codesads-api-sandbox.x.com not resolvingx ads api INVALID_PARAMETERx ads api UNAUTHORIZED_ACCESStwitter ads api error codes listx ads api bad authentication datax ads api sandbox hostnamex ads api 400 errorx ads apix ads api campaignsx api error codesx ads api creativesx ads costads api version 12x ads manager
DY
Deepak YadavBuilding X-Autopilot

Product designer and indie hacker. Runs the agent on his own X account every day and writes up what the data shows, including when it's inconvenient.

Follow on X →
Try X-Autopilot.
$199 once. No subscription, no monthly bill. Real Chrome on your Mac.
See pricing▶
Free PDF · the X Growth Playbook

The exact playbook we use to grow on X

The bio that converts, the daily reply loop, the posting cadence, and the tool stack, in one no-fluff PDF. Drop your email and it's yours.

No spam. Unsubscribe anytime.

Free tools

Try it yourself.

All free X tools →
Keep reading

Related posts.