1. Updates

Updating error result codes for 2026

Iframely API error responses now carry a stable code, a display-safe title, a detail message and retry hints. The error text field is deprecated and will be removed on July 1, 2027: read detail instead.

Iframely's original errors were designed to fit the oEmbed format and followed the industry's standard approach to error fields at the time. They gave you a status and a message written for people. The format was long overdue for a revamp, and the launch of Iframely's Data API required errors that machines could build on. The new Iframely format adopts current industry approaches to API errors, including parts of RFC 9457.

Errors now include the following fields; code, status and title are always present:

  • code, a stable machine-readable code such as origin.net.timeout or account.spending.blocked. The first part tells you where the problem is: your request (api), your account (account), the server behind the URL (origin), Iframely's checks of the page (iframely) or our own systems (system). Codes are safe to hard-code.
  • status: as before, a numeric result status, such as 404 or 417.
  • title and detail: a short summary you can show to users, and a description of this particular case.
  • retryable and retry_after: included when a retry can succeed, with the number of seconds to wait first. The wait is also sent as the Retry-After header.
  • origin_status and origin_code: when present, the HTTP status or network error from the server behind the URL.

An X-Error-Code HTTP header repeats the error code for your logs. As before, requests that end in an error are not counted as hits and are not billed.

Preview APIs return these fields at the top level of the response body. The Data API wraps them in an error object.

All codes, with a ready-to-use example, are in Result codes and error handling.

Deprecation notice: error is now detail

Preview API error responses still include the error text, as a copy of detail, so nothing breaks today. It is deprecated, though: read detail in new code, falling back to title when there is no detail, and move existing code off error before July 1, 2027.