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 with a status in the 4xx range, with a stable machine-readable code, a human-readable message and other fields:

{
	"error": {
		"code": "api.key.required",
		"status": 403,
		"title": "A valid API key is required"
	}
}

Depending on your settings, Iframely can also reiterate status as the HTTP status code of the API response for simpler error handling in a browser. By default, Iframely mutes these HTTP errors, which suits server-side handling. You get HTTP code 200 instead, as an “OK” signal about the API itself.

API requests that result in an error are not counted as hits and are not billed.

The error response

All endpoints return the same error fields. Preview APIs include all fields of an error at the top level of the response body, as a legacy of the oEmbed format. For the Data API, the error object is wrapped under a top-level error key for easier automated processing:

{
	"error": {
		"code": "origin.net.timeout",
		"status": 418,
		"title": "Could not fetch the URL in time",
		"detail": "Iframely could not fetch the given URL in a timely fashion. The page took too long to respond.",
		"retryable": true,
		"retry_after": 600,
		"origin_status": 408
	}
}

To detect an error, check for the error object on the /api/data endpoint, or for the top-level code on other endpoints:

const body = await response.json();

// /api/data
if (body.error && body.error.code) {
	const err = body.error;
}

// /api/iframely, /api/oembed, ...
if (body.code) {
	const err = body;
}

This works even in a browser because the HTTP response status is 200. For simpler error handling of legacy AJAX calls in a browser, you can use your API settings to receive the error’s status field as the HTTP status code.

The rest of this page refers to the fields of the error object, whichever way it arrives.

Error fields

code, status and title are always present. Other fields are optional — please tolerate their absence. We may add new fields over time; ignore the keys you don’t know.

FieldTypeMeaning
codestringStable machine-readable error code, e.g. api.key.required. Codes are never renamed or reused — safe to hard-code in your logic.
statusnumberThe canonical error status. Trust this over the HTTP status of the response.
titlestringShort, display-safe summary. Usually the same string for every occurrence of a code. For URL-fetch errors it may carry the first processing note instead, e.g. a robots.txt message.
detailstringHuman-readable description of this specific occurrence. Omitted when it would repeat title.
docsstringURL of relevant documentation, when available.
retryablebooleantrue when the error is transient and a retry may succeed. Absent means “do not retry”.
retry_afternumberSeconds to wait before retrying. Present only when retryable is true. Same value as the Retry-After header.
origin_statusnumberHTTP status the destination server answered with, when the failure came from fetching the URL.
origin_codestringRaw network or TLS error code from fetching the URL, e.g. ENOTFOUND, ECONNRESET, CERT_HAS_EXPIRED.

There is also a deprecated error field in all Preview API error responses. It is a copy of the detail field and is provided only to allow for legacy migrations. Please do not build new logic on it.

Response headers

HeaderContent
X-Error-CodeThe error code — useful for logs.
Retry-AfterIn seconds, same value as retry_after in the body, if present.

Error codes

Codes are dotted, lowercase, 2–3 levels: category.subject.condition, or where-what-how. The first segment tells where the error originated:

PrefixWhere it comes fromRecommended reaction
api.*your request — parameters, key, origin or host restrictionsfix the request or key setup; do not retry as-is
account.*your plan, usage, or API settingsupgrade, raise limits, or adjust your settings
origin.*the destination server of the requested URLretry only if retryable
iframely.*the Iframely robot raised an error for the URL based on page detailstreat the same way as origin.* errors; retry only if retryable
system.*Iframely internal systemslet us know and/or retry later

The second segment lets you match families without a lookup table. For example:

  • origin.http.* is an HTTP error status from the origin.
  • iframely.http.* is a similar HTTP error raised by the Iframely robot, for example a soft 404 or 403.
  • origin.net.* is a network or TLS failure.
  • api.key.* is an API key problem.
  • system.internal.* is an internal system error, like a 5xx.

In the unlikely event that you receive a 5xx internal error, please let us know so we can address the issue.

Exact matches like code === 'account.spending.blocked' are safe: codes are append-only. Match on prefixes for families and special-case only the codes you care about.

api.* — your request

codestatustitle
api.url.missing400A url parameter is required
api.url.multiple400A single url parameter is required
api.url.invalid422The URL is not valid
api.mode.required422A mode parameter is required (Data API)
api.key.required403A valid API key is required
api.referrer.required403A referrer header is required
api.origin.not_allowed403The request origin is not in the allowed list
api.endpoint.removed410The endpoint is no longer available

See allowed origins for api.origin.* and api.referrer.*.

account.* — your plan or settings

codestatustitle
account.app_name.required422An app_name is required for Data API use
account.plan.expired403A paid plan is required
account.spending.blocked403Configured spending limit reached
account.config.417417Data expectations not met
  • account.app_name.required — please configure your app name so we can present you to publishers on the Data API.
  • account.plan.expired — the free plan link limit is reached. API access is paused until you choose a plan.
  • account.spending.blocked — the spending limit you configured has been reached, and further API requests are blocked per your settings.
  • account.config.417 — your settings require specific data types (Data API) or HTML types (Preview API), and you asked to skip URLs without these types. These URLs, like any errors, are not billed. See What URLs to send to Iframely?.

origin.* — the requested URL

When the destination server answered with an HTTP error, the last segment of the code is that status verbatim: origin.http.403, origin.http.503, etc. The family is open-ended, so match on the origin.http. prefix and read the raw status from origin_status. The body status remains Iframely’s canonical status for the error:

codestatustitleretryable
origin.http.401403Content is private or requires a login
origin.http.403403Content is private or requires a login
origin.http.403403Publisher is blocking the Iframely robot
origin.http.404404Content is no longer available at the origin
origin.http.410410Content is no longer available
origin.http.406417The origin server responded with an erroryes
origin.http.429417The origin server rate-limited the fetchyes
origin.http.5xx417The origin server responded with an erroryes
origin.http.<other>417The origin server responded with an error
  • 404 means the URL is no longer available at the origin. 410 — “Gone” — is similar, but for URLs that were previously available. You can remove such obsolete URL data from your system.
  • 403 is for private pages that Iframely could not reach for processing. This is also the response when a publisher blocks Iframely entirely. When we cannot distinguish between the cases, we treat it as a private resource.
  • Upstream 408 and 418 are reported as origin.net.timeout, and upstream 415 as origin.content.unsupported.

Other cases when Iframely could not fetch the destination URL include these codes:

codestatustitleretryable
origin.net.timeout418Could not fetch the URL in timeyes
origin.net.dns_error404Could not resolve the URL host
origin.net.connection_error417Could not connect to the URL host
origin.net.connection_reset417Connection to the URL host was resetyes
origin.net.tls_error417Could not establish a secure connection to the URL host
origin.http.redirect_loop417Too many redirects while fetching the URL
origin.http.failed404 / 417Could not fetch the URLyes
origin.robots.disallowed415URL processing is disabled by the provider’s robots.txt
origin.content.unsupported415The URL content type is not supported

A few notes:

  • origin.net.timeout originally used the code 408. We changed it to 418 to avoid issues in your reverse proxies when this code is repeated as the HTTP status code. By default, Iframely expects origins to finish responding within 10 seconds and waits 10 minutes before retrying such timed-out URLs, to give the troubled server some time to recover. In some cases, when the timeout is signaled by a raw socket error, status may be 417 instead.
  • origin.content.unsupported — for example, ISO-2022 encoding or direct links to JavaScript files are not supported. We may also raise it for unrendered server templates of React or Angular origin servers.
  • For origin.net.* errors, origin_code carries the raw Node.js error code, such as ENOTFOUND, ETIMEDOUT, ECONNREFUSED, ECONNRESET, EPROTO, EAI_AGAIN, EHOSTUNREACH, ERR_SSL_* and more.
  • origin.http.failed and origin.http.redirect_loop are the non-numeric members of the family: the URL could not be fetched and no usable upstream status was captured. They never carry origin_status, so guard your parsing of the last segment against non-numeric values.
{
	"code": "origin.net.dns_error",
	"status": 404,
	"title": "Could not resolve the URL host",
	"origin_code": "ENOTFOUND"
}

iframely.* — errors raised by the Iframely robot

These are not origin errors: the URL itself was fetched successfully, or did not need to be fetched. Instead, Iframely concluded the URL cannot be served based on secondary information — the page’s meta tags or redirect behavior, or the response from a third-party API such as the provider’s oEmbed endpoint.

codestatustitleretryable
iframely.http.403403Iframely detected a soft 403 error
iframely.http.404404Iframely detected a soft 404 error
iframely.http.410410Iframely detected a soft 410 error
iframely.http.415415URL or provider is not supported
iframely.http.417417URL is not supported
iframely.http.429429Provider is rate-limiting at the momentyes
iframely.robots.disallowed415Automated processing is not allowed

Typical meanings:

  • 403 — the content is private or requires a login, even though the page itself loaded.
  • 404 / 410 — the resource is gone or does not exist, e.g. the provider’s API reported the media as deleted.
  • 415 — the URL is not supported by the system configuration.
  • 417 — data expectations were not met (missing or inconsistent meta, widget not available) and no fallback embed could be produced.
  • 429 — a third-party API Iframely relies on rate-limited us. Retryable.
  • iframely.robots.disallowed — Iframely concluded from the robots policy on the page that automated processing in the requested mode is not allowed, as opposed to origin.robots.disallowed, which is the robots.txt block.

The family is open-ended in the same way as origin.http.<status>: match on the iframely.http. prefix and read the status from status. The detail carries the message when one is available; origin_status and origin_code are usually absent.

system.internal.500 and other internal errors are another type of Iframely-caused error. Please report this unexpected case so we can address the issue.

system.http.<status> wraps a few legacy errors that don’t have their own code yet. Despite the system. prefix, these are not Iframely-side failures: read status and detail, and do not blanket-retry them. Expect them to migrate to proper api.* or account.* codes over time.

Retries

Retry only when retryable is true or for internal errors, and wait retry_after seconds (also sent as the Retry-After header) before doing so. For internal errors, wait an hour.

All other errors are deterministic: retrying the same request will produce the same error until the underlying cause changes — a fixed request, an upgraded plan, or a recovered origin and a refreshed cache.

Putting it together

const res = await fetch(`https://iframe.ly/api/data?url=${encodeURIComponent(url)}&api_key=${KEY}&mode=assist`);
const body = await res.json();

// /api/data nests the error; /api/iframely & co. return it flat.
const err = body.error && body.error.code ? body.error : body.code ? body : null;

if (err) {
	switch (err.code.split('.')[0]) {
		case 'api': // fix the request or setup — see err.code, err.detail, err.docs
		case 'account': // plan or limits — surface to your ops, back off
			if (err.code === 'account.config.417') {
				backoff(url, err.code);
				break;
			}
			throw new Error(`${err.code}: ${err.detail || err.title}`);


		case 'origin': // the URL itself is the problem
		case 'iframely': // Iframely decided the URL has no embed
			if (err.retryable) scheduleRetry(url, err.retry_after || 600);
			else backoff(url, err.code);
			break;

		case 'system': // Iframely side — but system.http.* is a legacy error, read its status
			if (err.code.startsWith('system.http.')) throw new Error(`${err.status}: ${err.detail || err.title}`);
			scheduleRetry(url, err.retry_after || 3600);
			break;

		default:
			throw new Error(`${err.code}: ${err.detail || err.title}`);
	}
} else {
	render(body); // normal payload
}

As Iframely is constantly evolving, we may need to introduce additional codes from time to time. Please let us know if you need any help interpreting our results.