DEV Community

Alex
Alex

Posted on

X's docs say 4 images. Their schema says 20. We tested which one was true.

We build a social media scheduler, so a tweet claiming "X just raised its image limit from 4 to 20" is the kind of thing that lands straight in our inbox. Before touching any code, we went looking for where that limit actually lives.

We found two answers that disagreed with each other.

Two sources, two numbers

X's own documentation, in plain prose, still says:

You can attach up to 4 photos, 1 animated GIF, or 1 video to a Tweet.

But the same page ships an OpenAPI schema for the same endpoint, and that schema says:

"media_ids": {
  "type": "array",
  "items": { "type": "string" },
  "maxItems": 20
}
Enter fullscreen mode Exit fullscreen mode

Four in the prose. Twenty in the machine-readable spec. No changelog entry, no date, nothing to say which one is current and which one is stale.

We've hardcoded platform limits before (character counts, file sizes, image counts) and the lesson that stuck is: a vendor's own docs are not guaranteed to agree with their vendor's own code. When they contradict each other, trust neither until you've asked the API directly.

What we did instead of guessing

We picked one of our own connected test accounts and ran a script that bypassed our app's publish pipeline entirely, so a wrong answer couldn't touch anything real:

// Upload 5 images directly, skip our own 4-item cap.
const mediaIds: string[] = [];
for (const file of testImages) {
  const uploadRes = await fetch("https://api.x.com/2/media/upload", {
    method: "POST",
    headers: { Authorization: `Bearer ${accessToken}` },
    body: mediaForm(file), // media_category: "tweet_image"
  });
  const { data } = await uploadRes.json();
  mediaIds.push(data.id);
}

const tweetRes = await fetch("https://api.x.com/2/tweets", {
  method: "POST",
  headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
  body: JSON.stringify({ text: "internal test, deleting shortly", media: { media_ids: mediaIds } }),
});
Enter fullscreen mode Exit fullscreen mode

Five uploads, one tweet, all five media IDs attached. If X still enforced 4, this would fail with a 4xx on the fifth media ID or on the tweet itself.

It didn't. X accepted the tweet with 5 images attached, no error. We deleted it immediately (DELETE /2/tweets/:id) and had our answer: the schema was right, the prose was stale.

The actual fix

One line, plus the error copy that quoted the old number:

// const MAX_IMAGES = 4;
const MAX_IMAGES = 20;
Enter fullscreen mode Exit fullscreen mode
// return { error: "X takes up to 4 images, or one video, or one GIF per post..." };
return { error: "X takes up to 20 images, or one video, or one GIF per post..." };
Enter fullscreen mode Exit fullscreen mode

The truncation logic (items.slice(0, MAX_IMAGES)) didn't need to change at all -- it was already written to use the constant, not a hardcoded number. That's the part worth doing in advance: when you cap something at a vendor's limit, cap it with a named constant, not a bare number sprinkled through the codebase. The day the vendor changes the limit, the fix is one line instead of a grep.

What we'd check before trusting either a changelog tweet or a vendor's own docs

  • If the docs and the schema disagree, the schema usually wins -- it's what their own server code is validated against, prose is what a writer typed and may never have been updated.
  • Test against a disposable resource, not production data. We used a test account and deleted the test post immediately after; the live API call was the only way to get a real answer, so make the blast radius as small as possible while you get it.
  • Cap vendor limits with a named constant, even when "it's just a 4" feels like overkill. The code that was already structured around MAX_IMAGES took one line to fix; code with 4 typed in three different places would have taken a grep and a prayer.
  • A third-party tweet about a platform change is a hypothesis, not a fact. Worth testing before shipping, worth ignoring if it turns out wrong -- either way, you want to know before your users find out for you.

We build Fuxux, a social media scheduler for creators. This check turned into a one-line fix the same afternoon the tweet showed up.

Top comments (0)