Result codes & error handling

If all goes well, Iframely responds with HTTP status code 200 and all JSON data. If there was a problem with URL or with your account, Iframely returns HTTP error code in 4xx range.

In addition to 4xx HTTP code, the JSON body of response will contains more details:

  "status": "404",
  "error": "Iframely could not fetch the given URL. The content is no longer available at the origin"

Please handle HTTP results 4xx in your code: those are valid responses and need to be cached.

Issues with requested URL

The destination URL is no longer available and provider replied with 404 or 5xx error, or there was a problem establishing a connection to the server.
Gone. Similar to 404, but for URLs that were previously available but now return HTTP errors. You can remove obsolete URL data from your system now.
401 or 403
For private pages that Iframely could not reach for processing. Or if the robots directive on the page prevents Iframely from parsing it.
For unsupported media types. For example, ISO-2022 encoding or direct links to Flash and JavaScript files are not supported. May also be returned for React or Angular apps if Iframely could not render the templates.

Originally 408 (changed not to cause any issues in your reverse proxies), time-out is returned when origin server takes too long to respond.

By default, Iframely expects origins to finish responding within 10 seconds. Iframely will wait 10 mins before re-trying such timed-out URLs again to give the troubled origin some time to recover.

Your account or API settings

If request cannot be authorized: API key isn't valid, account is not in good standing, or the origin of API call is blocked by your settings (more about blocking origins).

The expectation failed. Returned if you opted to ignore any URLs that do not yield rich media embed codes allowed in your API settings or if the origin server responds with 5xx HTTP error (e.g. we get 503 - service not available).

417 is also returned if you explicetely blacklisted that publisher via your API settings (see below).

URLs that result in error do not register hits towards your API usage and are not included in your stats. Morever, you can configure Iframely to raise code 417 for particular URL if our parsers could not discover or generate rich media embed codes that matches your settings and filters. Such URLs will not affect your billing stats. Read more about our whitelisting approach.

In an unlikely event that you received 5xx HTTP error, please let us know right away so that we can address our own server-side problem.

Previous article: API parameters
Next article: Embed.js