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.
| Field | Type | Meaning |
|---|---|---|
code | string | Stable machine-readable error code, e.g. api.key.required. Codes are never renamed or reused — safe to hard-code in your logic. |
status | number | The canonical error status. Trust this over the HTTP status of the response. |
title | string | Short, 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. |
detail | string | Human-readable description of this specific occurrence. Omitted when it would repeat title. |
docs | string | URL of relevant documentation, when available. |
retryable | boolean | true when the error is transient and a retry may succeed. Absent means “do not retry”. |
retry_after | number | Seconds to wait before retrying. Present only when retryable is true. Same value as the Retry-After header. |
origin_status | number | HTTP status the destination server answered with, when the failure came from fetching the URL. |
origin_code | string | Raw 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
| Header | Content |
|---|---|
X-Error-Code | The error code — useful for logs. |
Retry-After | In 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:
| Prefix | Where it comes from | Recommended reaction |
|---|---|---|
api.* | your request — parameters, key, origin or host restrictions | fix the request or key setup; do not retry as-is |
account.* | your plan, usage, or API settings | upgrade, raise limits, or adjust your settings |
origin.* | the destination server of the requested URL | retry only if retryable |
iframely.* | the Iframely robot raised an error for the URL based on page details | treat the same way as origin.* errors; retry only if retryable |
system.* | Iframely internal systems | let 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 soft404or403.origin.net.*is a network or TLS failure.api.key.*is an API key problem.system.internal.*is an internal system error, like a5xx.
In the unlikely event that you receive a
5xxinternal 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
code | status | title |
|---|---|---|
api.url.missing | 400 | A url parameter is required |
api.url.multiple | 400 | A single url parameter is required |
api.url.invalid | 422 | The URL is not valid |
api.mode.required | 422 | A mode parameter is required (Data API) |
api.key.required | 403 | A valid API key is required |
api.referrer.required | 403 | A referrer header is required |
api.origin.not_allowed | 403 | The request origin is not in the allowed list |
api.endpoint.removed | 410 | The endpoint is no longer available |
See allowed origins for api.origin.* and api.referrer.*.
account.* — your plan or settings
code | status | title |
|---|---|---|
account.app_name.required | 422 | An app_name is required for Data API use |
account.plan.expired | 403 | A paid plan is required |
account.spending.blocked | 403 | Configured spending limit reached |
account.config.417 | 417 | Data 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:
code | status | title | retryable |
|---|---|---|---|
origin.http.401 | 403 | Content is private or requires a login | |
origin.http.403 | 403 | Content is private or requires a login | |
origin.http.403 | 403 | Publisher is blocking the Iframely robot | |
origin.http.404 | 404 | Content is no longer available at the origin | |
origin.http.410 | 410 | Content is no longer available | |
origin.http.406 | 417 | The origin server responded with an error | yes |
origin.http.429 | 417 | The origin server rate-limited the fetch | yes |
origin.http.5xx | 417 | The origin server responded with an error | yes |
origin.http.<other> | 417 | The origin server responded with an error |
404means 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.403is 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
408and418are reported asorigin.net.timeout, and upstream415asorigin.content.unsupported.
Other cases when Iframely could not fetch the destination URL include these codes:
code | status | title | retryable |
|---|---|---|---|
origin.net.timeout | 418 | Could not fetch the URL in time | yes |
origin.net.dns_error | 404 | Could not resolve the URL host | |
origin.net.connection_error | 417 | Could not connect to the URL host | |
origin.net.connection_reset | 417 | Connection to the URL host was reset | yes |
origin.net.tls_error | 417 | Could not establish a secure connection to the URL host | |
origin.http.redirect_loop | 417 | Too many redirects while fetching the URL | |
origin.http.failed | 404 / 417 | Could not fetch the URL | yes |
origin.robots.disallowed | 415 | URL processing is disabled by the provider’s robots.txt | |
origin.content.unsupported | 415 | The URL content type is not supported |
A few notes:
origin.net.timeoutoriginally used the code408. We changed it to418to 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,statusmay be417instead.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_codecarries the raw Node.js error code, such asENOTFOUND,ETIMEDOUT,ECONNREFUSED,ECONNRESET,EPROTO,EAI_AGAIN,EHOSTUNREACH,ERR_SSL_*and more. origin.http.failedandorigin.http.redirect_loopare the non-numeric members of the family: the URL could not be fetched and no usable upstream status was captured. They never carryorigin_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.
code | status | title | retryable |
|---|---|---|---|
iframely.http.403 | 403 | Iframely detected a soft 403 error | |
iframely.http.404 | 404 | Iframely detected a soft 404 error | |
iframely.http.410 | 410 | Iframely detected a soft 410 error | |
iframely.http.415 | 415 | URL or provider is not supported | |
iframely.http.417 | 417 | URL is not supported | |
iframely.http.429 | 429 | Provider is rate-limiting at the moment | yes |
iframely.robots.disallowed | 415 | Automated 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 toorigin.robots.disallowed, which is therobots.txtblock.
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.