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.
On this page · 11 sections
- Quick answer
- The sandbox host does not exist
- 77 constants, 10 status codes
- The table is not complete
- The status code does not follow the name
- The error you will actually get first
- The one example in the docs is not what the API sends
- A 200 is not always a success
- Rate limiting, and a reference that is gone
- Nothing is shared with the v2 API
- The bottom line
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.
| Resolver | Result for ads-api-sandbox.x.com |
|---|---|
| System resolver | NXDOMAIN |
| Google, 8.8.8.8 | NXDOMAIN |
| Cloudflare, 1.1.1.1 | NXDOMAIN |
| Google DNS-over-HTTPS | Status 3, authoritative SOA from a.u10.twtrdns.net |
Control: ads-api.x.com | CNAME 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:
| HTTP | Constants |
|---|---|
| 404 | 28 |
| 400 | 28 |
| 403 | 12 |
| 503 | 2 |
| 429 | 2 |
| 500, 423, 408, 405, 401 | 1 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_FOUNDreturns 403USER_NOT_FOUNDreturns 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:
| Request | HTTP | Body |
|---|---|---|
GET /12/accounts | 400 | code: 215, Bad Authentication data |
GET /12/accounts/abcdefg/campaigns | 400 | code: 215, Bad Authentication data |
GET /12/line_items/placements | 400 | code: 215, Bad Authentication data |
GET /99/accounts | 400 | code: 215, Bad Authentication data |
GET /12/nonexistent_route_test | 401 | UNAUTHORIZED_ACCESS with a request node |
Same two shapes on ads-api-sandbox.twitter.com | 400 / 401 | Identical |
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 API | X API v2 | |
|---|---|---|
| Envelope | errors[] plus request | Flat object |
| Identifier | code, CAPS_CASE or integer | type, a URI |
| Auth failure status | 400 | 401 |
| Published inventory | 77 in a table | 61 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.
- X developer docs, Ads API 'Error codes and responses': the 77-row table of CAPS_CASE constants with their HTTP status codes, the errors/code and errors/message response contract, the single INVALID_PARAMETER example showing parameter, details, code, value and message, and the statement that error responses are served with a non-200-series HTTP code (accessed 15 November 2026)
- X developer docs, Ads API 'Sandbox': the instruction to call the hostname ads-api-sandbox.x.com, the note that sandbox campaigns are never served to users, and the list of six sandbox-only endpoints for accounts, account features and funding instruments (accessed 15 November 2026)
- DNS resolution checks for ads-api-sandbox.x.com returning NXDOMAIN from the system resolver, 8.8.8.8 and 1.1.1.1, and Status 3 from Google DNS-over-HTTPS with the authoritative x.com SOA; ads-api-sandbox.twitter.com resolving via CNAME to s.twitter.com and answering on HTTPS with a wildcard twitter.com certificate dated 13 November 2026 (run 15 November 2026)
- X Developers forum, 'Stats endpoint returns an unformatted INVALID_PARAMETER (entity) error for one ad account', posted 10 November 2026 with no reply: the literal unsubstituted message Expected %s, got "%s" for %s, the empty request.params node, and the Asia/Kolkata half-hour offset account failing where Europe/Madrid and America/Los_Angeles succeed
- X developer docs, Ads API 'Rate limiting': the user-level and ad-account-level header families, the 450-per-minute shared write bucket, the five-per-15-minutes ceiling on global reads without an account_id, and the primary reference link to developer.x.com that 307-redirects to a homepage (accessed 15 November 2026)
- X developer docs, Ads API 'Catalog Management API Reference': the PUT product_catalogs/:product_catalog_id/products response parameters, including per-product warnings and errors arrays and a status enum of CREATE_SUCCESS, UPDATE_SUCCESS, ERROR and NO_CHANGE (accessed 15 November 2026)
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 →