Result codes & error handling

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

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

Depending on your app's settings, Iframely can also repeat status as HTTP status code of API response.

When configured and when URL has issues, HTTP status codes in 4xx range make for easier onerror handlers in client-side environments. By default, Iframely mutes such HTTP errors and you always get HTTP code 200 instead to signal that the API itself works well.

Please handle 4xx result codes: these 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 destination 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.
403 or 401
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 explicitly 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. Moreover, you can configure Iframely to raise code 417 for particular URL if our parsers could not discover or generate rich media embed codes that match your settings and filters. Such URLs hits will not affect your billing. 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