I want to specify an alternative image that will be displayed when oEmbed fails.

The specific use case is to offer an alternative when China (or other countries) block YouTube. We know the YouTube content won't be available there, but want to provide an alternate image in that case.

Can the oEmbed error code be made accessible for this purpose?

  • Very interesting question. Unfortunately I don't have an anwer for you, but this is definitely something worth looking into. Apr 5, 2015 at 7:16
  • 1
    I've been looking into this issue. I've gone quite deep but I've not found any solution. The problem is that the oEmbed request is done from the web server, not from client side. In the server everything is OK and the embed HTML is returned by YouTube; that is, the iframe that load the video. When the client try to load the iframe content, is when the content is blocked. As far I can understand, oEmbed doesn't fail and there is nothing or very little we can do. Expecting what others think about this.
    – cybmeta
    Apr 5, 2015 at 10:24
  • I think, not sure, the API of oembed works about RESTful API. This API return an answer to the client like this one GET /photos/bees/2362225867/ HTTP/1.1 Host: flickr.com Accept: application/oembed+xml. Alternative is the default to get a error http code, like 406 Not Acceptable. This should be useful for return a message.
    – bueltge
    Apr 5, 2015 at 16:03
  • @bueltge the returned answer from oEmbed is not send to the client. Not at least for YouTube as I said in my comment. The oEmbed request is done server side, YouTube returns a <iframe> HTML and that is what is embeded in the post and that is what is server to the client: a <iframe>. When the client from China try to load the content of the <iframe> is when it is blocked. There is nothing server side involved. I've not tested with other oEmbed providers but I think they all work in a similar way. In fact, if the oEmbed would be done client side there wouldn't be any real content embeded.
    – cybmeta
    Apr 8, 2015 at 18:30
  • 1
    The only alternative i see is to check the embedded content by javascript. if you dont get the video iframe, you may show something else ...
    – jjarolim
    Apr 19, 2015 at 20:40

2 Answers 2


I think the best thing to do in this case is to wrap your oEmbed content with a div before they are rendered and then show an alternate image with the CSS background-image property. If the video loads, then the oEmbed content will cover the background image.

You can add the wrapper using the embed_oembed_html filter.

add_filter('embed_oembed_html', 'your_function_here');

If you're worried about loading in extra elements, then you can do a client side check with JS to see if the oEmbed loaded, and if not, load a background image into the wrapper.

You could get a lot more complicated by adding in custom fields for each video, but that's essentially the gist of it.


One approach might be to make another request using oEmbed on the server side via a proxy which is based in China.

This way you would know ahead of time if the call to the resource on the client is going to fail. Early on in the page request you can ascertain where the client's IP is located geographically, make a server-side call via a proxy to the resource e.g youtube and then leverage the oEmbed error you'll presumably get.

You could take a look at Wonderproxy for achieving this (I am not affiliated with them but hear good things)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.