---
title: "Iframely result codes and error handling"
description: "Here are the error codes you might receive from Iframely and how to handle them"
---

# 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:

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

Depending on your [settings](/settings/errors), 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:

```json
{
	"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:

```js
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](mailto:support@iframely.com) 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](mailto:support@iframely.com) 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](/docs/allow-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?](/docs/providers).

### `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    |             |

- `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:

| `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.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](https://nodejs.org/api/errors.html#nodejs-error-codes), 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.

```json
{
	"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 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

```js
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.