Skip to main content

attachment_fetch_failed

An attachment was supplied as a URL, and that URL could not be read when the message was sent. The message was not delivered.

Status: 422

{
  "status": 422,
  "type": "attachment_fetch_failed",
  "message": "failed to fetch attachment from url: ...",
  "request_id": "req_01J8K2P...",
  "doc_url": "https://docs.epostix.com/errors/attachment_fetch_failed"
}

The reason is appended to message, so read it first. Branch on type, never on the wording.

Why you got this​

  • The URL did not respond, or the request to it timed out.
  • It answered with a non-2xx status: 404 for a file that moved, 403 for one behind authentication.
  • The URL resolves to a private or internal address. Only publicly reachable hosts are fetched.
  • The file it serves is over the size limit.

How to fix it​

Open the URL from outside your own network with no credentials and confirm it returns the file you expect. Presigned and expiring links are a frequent cause: the URL is read when the message is sent, not when you submit it, so a link that was valid at submission can be dead by the time it is needed.

For files you control, upload them with POST /attachments and send the returned id. That removes the fetch entirely, at the cost of a 24 hour lifetime on the id, after which it returns attachment_expired.

Is it safe to retry​

Yes, once the URL serves the file. The message was not delivered, so a retry cannot duplicate it.

Reusing the Idempotency-Key is safe, because a rejected request was never stored.