X API error codes: 11 documented, 61 in the spec
X's error reference lists 11 problem types. Its live OpenAPI spec declares 61, five of the documented ones do not exist, and about:blank is in neither.
On this page · 11 sections
- Quick answer
- The two sources, side by side
- What the docs list that the API does not have
- What the API has that the docs never list
- 43 of 61 are DM errors
- The two problems that still live on api.twitter.com
- about:blank is the one you will actually hit
- Rate limit headers are not guaranteed
- The Ads API is a third vocabulary
- How to actually handle this
- The bottom line
The short version
- ▸X's error reference page lists 11 problem types. The live OpenAPI spec at api.x.com/2/openapi.json declares 61 in a discriminated union keyed on the type field. The documentation shows under a fifth of the vocabulary your client will actually receive.
- ▸Five of the types X documents appear nowhere in the spec, not even as a bare string: client-forbidden, usage-capped, rate-limit-exceeded, streaming-connection and rule-cap. Six general-purpose types in the spec are missing from the docs, including internal-error and field-unauthorized.
- ▸about:blank is documented as a valid type and it is what a live 401 actually returns, but it has no entry in the spec's discriminator mapping. A client generated strictly from X's own spec cannot deserialise X's most common error body.
- ▸43 of the 61 types are dm-* prefixed and 7 more are chat or encryption related. Messaging accounts for 50 of 61. That leaves exactly 11 general-purpose problem types, and only 5 of them overlap with the 11 the docs list.
- ▸The docs say every response includes rate limit headers. A 401 from GET /2/tweets on 15 November 2026 returned no x-rate-limit header of any kind, so do not write a parser that assumes they are present.
Quick answer
X publishes two error vocabularies for one API and they do not match. The Response Codes and Errors page lists 11 problem types. The live OpenAPI spec at api.x.com/2/openapi.json declares 61 of them in a discriminated union, 43 of which are DM failures. Five types X documents are absent from the spec entirely, six general-purpose types in the spec are missing from the docs, and about:blank - the type a plain 401 actually returns - appears in neither the spec's mapping nor any list of what to do about it. Build your error handling off the spec, not the page.
Last updated: November 2026
If you are debugging an X (formerly Twitter) integration, the reference page you land on from search is a summary, not an inventory. Here is the real inventory, where it came from, and the four places the two sources contradict each other.
The two sources, side by side
X's human-facing error page gives you a three-field body:
{
"title": "Invalid Request",
"detail": "The 'query' parameter is required.",
"type": "https://api.x.com/2/problems/invalid-request"
}
Then a table of 11 types: about:blank, invalid-request, resource-not-found, not-authorized-for-resource, client-forbidden, usage-capped, rate-limit-exceeded, streaming-connection, rule-cap, invalid-rules and duplicate-rules.
X's spec tells a different story. components.schemas.Problem is a oneOf across 61 variants with a discriminator whose propertyName is type and whose mapping has 61 keys. That is not a documentation convenience. A discriminator is a contract: it says the type field is the tag, and these are the tags.
| Source | Types | Shape |
|---|---|---|
| Response Codes & Errors page | 11 | Prose table, 3 fields described |
api.x.com/2/openapi.json v2.174 | 61 | oneOf + discriminator mapping |
It also documents fields the page never mentions. ResourceNotFoundProblem declares status as an integer, plus parameter, value, resource_id and resource_type, and marks type, title, detail and resource_type as required. The page's field table has three rows.
What the docs list that the API does not have
Five of the documented types do not appear in the spec. Not as a discriminator key, not as an enum value, not as a bare string anywhere in the 1.35 MB JSON document:
client-forbiddenusage-cappedrate-limit-exceededstreaming-connectionrule-cap
That does not prove the API never sends them. It does mean nobody writing a code generator, a schema validator or a typed client will get a branch for them, and X's own machine-readable contract disclaims them. If your retry logic keys on rate-limit-exceeded, log what your 429s actually carry before you ship it, because the spec gives you no grounds to expect that string.
What the API has that the docs never list
Strip the messaging types out of the spec and you are left with exactly 11 general-purpose problems, a coincidence of arithmetic that makes the mismatch easy to miss:
| Type | In the docs? |
|---|---|
invalid-request | Yes |
resource-not-found | Yes |
not-authorized-for-resource | Yes |
invalid-rules | Yes |
duplicate-rules | Yes |
internal-error | No |
resource-unavailable | No |
disallowed-resource | No |
field-unauthorized | No |
not-authorized-for-field | No |
field-hydration-failure | No |
Those bottom six are the interesting ones. field-unauthorized, not-authorized-for-field and field-hydration-failure are all about fields expansions failing for one requested field while the rest of the object comes back fine, which is precisely the partial-failure case that bites people building dashboards. None of the three is on the documented list. If you are pulling expansions, read X API expansions for what each one costs before you add more of them to a request that is already failing.
43 of 61 are DM errors
Here is the distribution nobody mentions:
| Group | Count |
|---|---|
dm-* | 43 |
| Chat, XChat and encryption | 7 |
| General purpose | 11 |
Messaging is 50 of 61 problem types. That is not X being sloppy; it is an honest reflection of how many ways one DM send can be refused, and it lines up with the 43 refusal paths catalogued in X API DM. Blocked recipient, closed DMs, unverified sender, phone required, read-only sender, safety-limited, safety-rejected, encryption required, device inactive: each is its own type with its own schema.
In practice, if you are not sending DMs, your realistic error surface is eleven types and change, and you can write an exhaustive switch over it in an afternoon. If you are sending DMs, you cannot, and you should be logging the raw type string rather than mapping it to an internal enum.
The two problems that still live on api.twitter.com
59 of the 61 type URIs are rooted at https://api.x.com/2/problems/. Two are not:
https://api.twitter.com/2/problems/invalid-rules
https://api.twitter.com/2/problems/duplicate-rules
Both are filtered-stream rule errors, and both are in the live discriminator mapping with the old host. Any client that matches on a prefix, or that normalises api.twitter.com to api.x.com before comparing, will drop them on the floor. If you manage stream rules programmatically, compare on the last path segment instead. X API stream covers what else is different about the rules endpoints.
about:blank is the one you will actually hit
This is the finding that changes code. On 15 November 2026, an unauthenticated request to GET https://api.x.com/2/tweets returned:
{
"title": "Unauthorized",
"type": "about:blank",
"status": 401,
"detail": "Unauthorized"
}
Note three things. The body carries status, a field the docs' table does not list. The type is about:blank. And about:blank has no entry in the spec's discriminator mapping, which means a client generated from X's own OpenAPI document has no variant to deserialise this into. The most common error response the API sends is the one its machine-readable contract does not describe.
Fixing it is dull but necessary: treat type as an optional hint, branch on HTTP status first, and keep a fallback case. Do not make type a required tagged-union discriminant in your own types, however tempting the spec makes it look.
Rate limit headers are not guaranteed
The error page says, under a heading of its own, that "every response includes rate limit information" and shows x-rate-limit-limit, x-rate-limit-remaining and x-rate-limit-reset.
That 401 came back with cache-control, x-transaction-id, x-response-time, strict-transport-security and x-served-by. No rate limit header of any kind. That is defensible behaviour, since an unauthenticated caller has no quota to report against, but it is not what the page promises, and a client that reads x-rate-limit-reset unconditionally will throw on the error path rather than the success path. Which of the documented limits actually applies to you is its own mess, covered in X API rate limits.
The Ads API is a third vocabulary
Worth stating plainly, because people assume one company means one error format. It does not.
| X API v2 | X Ads API | |
|---|---|---|
| Envelope | Flat object | errors[] plus a request node |
| Code field | type, a URI | code, a CAPS_CASE constant |
| Status on auth failure | 401 | 400 |
| Count | 61 types in the spec | 77 constants in a table |
They share no field names beyond errors. A parser written for one cannot read the other, and there is no published crosswalk between them. The Ads side has its own set of problems, including an error body whose placeholders never get filled in.
How to actually handle this
Four rules that survive both vocabularies:
- Branch on HTTP status first,
typesecond. Status is always present and always meaningful.typeis optional in practice. - Check for an
errorskey on every 200. Partial success is a documented shape and it is how multi-resource requests degrade. - Log the raw error body, unparsed, before you touch it. With 61 types and a spec that does not cover
about:blank, your logs are the only complete record of what you are receiving. - Fetch the spec yourself and diff it.
api.x.com/2/openapi.jsonneeds no auth and no key. It is the only authoritative inventory, and as X API OpenAPI spec sets out, it moves faster than the pages describing it.
If you are reading this because you are trying to automate posting and replies and keep hitting 403s, the error vocabulary may not be your real problem. The API route has been narrowing since February 2026, and some refusals are policy rather than code. X-Autopilot takes the other route, driving your own browser on your own machine rather than calling the API, which is a different trade with its own risks rather than a free pass. It is a gray area, not sanctioned, and we say so on the download page.
The bottom line
X documents 11 error types and ships 61. Five of the eleven do not exist in its own spec, six of the spec's general-purpose types never made the page, two still carry the pre-rename hostname, and the one you will see most often is unmapped. None of this is catastrophic, but all of it is the kind of thing that turns a two-hour integration into a two-day one when you trusted the summary page and generated a client from the spec at the same time. Pick the spec, keep a default branch, and log everything.
Frequently asked
Answers indexed by Google + AI assistants.
How many error codes does the X API have?+
It depends which source you trust. X's Response Codes and Errors page lists 11 problem types and 13 HTTP status codes. The live OpenAPI spec at api.x.com/2/openapi.json, version 2.174 when fetched on 15 November 2026, declares 61 distinct problem type URIs as a oneOf union with a discriminator on the type field. Those 61 are the set the API can actually emit, and the spec is the only place the full list exists.
What does about:blank mean in an X API error?+
It is the generic problem type, and it means the type field carries no extra information so you have to read the HTTP status instead. It is also the body you get most often: an unauthenticated GET https://api.x.com/2/tweets returns 401 with type about:blank, title Unauthorized, status 401 and detail Unauthorized. The catch is that about:blank has no entry in the spec's discriminator mapping, so a strictly generated client will fail to match it against any Problem variant.
Why does my X API client fail to parse some error responses?+
Most likely because it was generated from the OpenAPI spec and the response used about:blank, or because it switches on the type URI and hit one of the two rule errors. invalid-rules and duplicate-rules are declared in the spec under the legacy api.twitter.com host while the other 59 use api.x.com, so an exact string comparison against an api.x.com prefix will silently miss both.
What is the difference between a 401 and a 403 on the X API?+
A 401 means the credentials were missing, malformed or rejected, so nothing about your request body was evaluated. A 403 means you authenticated fine and the API refused the action anyway, usually with a specific type such as not-authorized-for-resource or client-forbidden. The practical tell is that retrying a 401 with the same token is pointless, while a 403 is often about scopes, access level or the specific resource rather than the token itself.
Does the X API return errors inside a 200 response?+
Yes, and this is the failure mode most clients miss. A request for several resources can partially succeed and return HTTP 200 with both a data array and an errors array, where each entry carries resource_id, resource_type, title, detail and a type URI. Checking the status code alone will make you treat a half-empty response as a complete one, so check for an errors key on every 200.
Where is the official list of X API error codes?+
There are two official lists and they do not agree. The human-readable one is at docs.x.com/x-api/fundamentals/response-codes-and-errors. The machine-readable and far more complete one is the Problem schema inside api.x.com/2/openapi.json, which needs no authentication to fetch. The Ads API is a third vocabulary entirely, using CAPS_CASE string constants rather than type URIs.
- X developer docs, 'Response Codes & Errors': the 13 HTTP status codes, the 11 listed error types including about:blank, the three-field error format of type, title and detail, the partial-errors-inside-200 example, and the statement that every response includes rate limit information (accessed 15 November 2026)
- X API live OpenAPI specification, api.x.com/2/openapi.json, info.version 2.174 with 202 paths: the Problem base schema as a oneOf of 61 variants with a discriminator on type, the 61-entry mapping of type URIs to schemas, 43 dm-prefixed variants, the two rule problems declared under api.twitter.com, and the absence of any about:blank mapping (fetched and parsed 15 November 2026)
- X developer docs, Ads API 'Error codes and responses': the separate CAPS_CASE error vocabulary of 77 constants mapped to 10 HTTP status codes, and the errors/code plus errors/message response shape (accessed 15 November 2026)
- Live probe of GET https://api.x.com/2/tweets with no credentials: HTTP 401 with body containing title Unauthorized, type about:blank, status 401 and detail Unauthorized, and response headers containing no x-rate-limit-limit, x-rate-limit-remaining or x-rate-limit-reset (run 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 →