1. Docs
  2. API endpoints

Result codes, error handling

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

{
	"status": "403",
	"error": "Valid api_key is required to access API"
}

Depending on your app’s settings, Iframely can also reiterate status as the HTTP status code of API response. By default, Iframely mutes such HTTP errors. You always get HTTP code 200 instead as an “OK” signal about the API status itself.

Please handle all 4xx result codes: these are valid responses and need to be cached.

Issues with requested URL

404

The destination URL is no longer available at the origin. Provider replied with 404 or 5xx error, or there was a problem establishing a connection to the destination server.

410

“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.

415

“Unsupported media types”. For example, ISO-2022 encoding or direct links to JavaScript files are not supported.

If we see unrendered server templates, we may raise a 415 code for React or Angular origin servers. You users don’t need to see it in URL meta.

418

Originally the code 408, we changed it not to cause any issues in your reverse proxies. We raise “timeout” code when an 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 server some time to recover.

Your account or API settings

403

If the API request cannot be authorized:

  • An API key isn’t valid.
  • An account is not in good standing.
  • Your settings do not allow an origin of the API call (about blocking referrers).

417

The “expectation failed”.

  • Returned if you opted to ignore URLs that do not yield third-party rich media or an Iframely interactive.
  • When the origin server responds with 5xx HTTP error (e.g. we get 503 — service not available).
  • When explicitly block specific publisher domain via your API settings (see below).

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

See also