# Error codes

## Table of Contents

- [EAUTH](#eauth)
- [ECACHEKEY](#ecachekey)
- [EBRWSRTIMEOUT](#ebrwsrtimeout)
- [ECONCURRENCY](#econcurrency)
- [EFATAL](#efatal)
- [EFILENAME](#efilename)
- [EFATALCLIENT](#efatalclient)
- [EFORBIDDENURL](#eforbiddenurl)
- [EHEADERS](#eheaders)
- [EHTMLNESTED](#ehtmlnested)
- [EINVALURL](#einvalurl)
- [EINVALPROXY](#einvalproxy)
- [EINVALURLCLIENT](#einvalurlclient)
- [EINVALTTL](#einvalttl)
- [EINVALEVAL](#einvaleval)
- [EINVALFUNCTION](#einvalfunction)
- [EINVALDATA](#einvaldata)
- [EINVALQUERY](#einvalquery)
- [EINVALSTTL](#einvalsttl)
- [EINVALOVERLAYBG](#einvaloverlaybg)
- [EINTEGRATION](#eintegration)
- [EMAXREDIRECTS](#emaxredirects)
- [EPAGERANGE](#epagerange)
- [EPDFTOOLARGE](#epdftoolarge)
- [EPRO](#epro)
- [EPROXY](#eproxy)
- [EPROXYNEEDED](#eproxyneeded)
- [ERATE](#erate)
- [ETIMEOUT](#etimeout)
- [EUNREACHABLE](#eunreachable)
- [ETTL](#ettl)
- [ESTTL](#esttl)

---

Microlink API considers an unexpected situation any request performed on which [status](https://microlink.io/docs/api/basics/format#status) is different from 'success'.

When this happens, the response payload includes some useful information in order to determine the root cause of the problem:

- `id`: The unique identifier associated with the request.
- `code`: The error code that represents the final request state.
- `message`: A brief explanantion about why the error happened.
- `more`: A link pointing this documentation.
- `report`: A link for reporting the problem directly to us.

If you are experience any of these errors are you not sure how to proceed, please feel free to [reach us](mailto:hello@microlink.io).

## EAUTH

**Message**

Invalid API key. Make sure you are attaching your API key as `x-api-key` header.

**Solution**

Ensure to [authenticate](https://microlink.io/docs/api/basics/authentication) your requests providing an API key attached as `x-api-key`.

## ECACHEKEY

**Message**

You need a

PRO

plan for using [cacheKey](https://microlink.io/docs/api/parameters/cacheKey) query parameter.

**Solution**

See [pricing](https://microlink.io/pricing) for upgrading your plan.

## EBRWSRTIMEOUT

**Message**

The URL provided reached the maximum browser navigation time allowed.

**Solution**

When the target [url](https://microlink.io/docs/api/parameters/url) reached the [timeout](https://microlink.io/docs/api/parameters/timeout) associated with the request lifecycle, this error is thrown.

In order to avoid this error, the request should be resolved before timeout. The maximum is 30 seconds on the free endpoint and 60 seconds with an API key.

## ECONCURRENCY

**Message**

Too many concurrent requests (limit: 2). Wait for one to finish or upgrade to a PRO plan.

**Solution**

Without an API key, each IP address runs up to 2 requests at the same time, and up to 2 copies of the same function per URL. The free API key answers with the same code when it goes over its limit. Wait a second and retry, or upgrade to a [paid plan](https://microlink.io/pricing). See [rate limit](https://microlink.io/docs/api/basics/rate-limit).

## EFATAL

**Message**

Resolved the target URL failed. Make sure your URL is valid and it has HTML content.

**Solution**

This is the generic error used when it wasn't possible to determine the root cause of the problem.

If you are experimenting with this error, please [contact us](mailto:hello@microlink.io), reporting the request `id` to make it possible to reproduce the original request.

## EFILENAME

**Message**

You need a

PRO

plan for using [filename](https://microlink.io/docs/api/parameters/filename) query parameter.

**Solution**

See [pricing](https://microlink.io/pricing) for upgrading your plan.

## EFATALCLIENT

**Message**

(no message)

**Solution**

There is a network problem trying to reach the API [endpoint](https://microlink.io/docs/api/basics/endpoint).

If you are experimenting with this error, please [contact us](mailto:hello@microlink.io).

## EFORBIDDENURL

**Message**

The URL is being resolved into an IP address whose range is not allowed.

**Solution**

The service will only resolve URLs that point to unicast IP addresses.

## EHEADERS

**Message**

You need a

PRO

plan for using [headers](https://microlink.io/docs/api/parameters/headers) query parameters, or the Lighthouse `extraHeaders` and `emulatedUserAgent` settings.

**Solution**

See [pricing](https://microlink.io/pricing) for upgrading your plan.

## EHTMLNESTED

**Message**

The document is too deeply nested to read as HTML.

**Solution**

The target is XML or another document whose tags do not close the way HTML expects, so it cannot be read back as HTML.

Request the file directly, or pass a page that is HTML.

## EINVALURL

**Message**

The target URL is considered not valid.

**Solution**

Ensure the [url](https://microlink.io/docs/api/parameters/url) provided has protocol, hostname and follows [WHATWG URL](https://nodejs.org/api/url.html#url_the_whatwg_url_api) standard.

## EINVALPROXY

**Message**

The proxy URL is considered not valid.

**Solution**

Ensure the [proxy.url](https://microlink.io/docs/api/parameters/proxy/url) provided can be parsed as [WHATWG URL](https://nodejs.org/api/url.html#url_the_whatwg_url_api).

## EINVALURLCLIENT

**Message**

The target URL is considered not valid.

**Solution**

Ensure the [url](https://microlink.io/docs/api/parameters/url) provided has protocol, hostname and follows [WHATWG URL](https://nodejs.org/api/url.html#url_the_whatwg_url_api) standard.

## EINVALTTL

**Message**

The `ttl` value is invalid.

**Solution**

The [ttl](https://microlink.io/docs/api/parameters/ttl) value should be a value between '1m' to '31d' range.

## EINVALEVAL

**Message**

The `function` evaluation failed.

**Solution**

The [function](https://microlink.io/docs/api/parameters/function) code was executed but failed during evaluation. This typically means your function threw an error or encountered a runtime exception. Check your function code for:

- JavaScript runtime errors
- Undefined variables or functions
- Incorrect operations on the page data

## EINVALFUNCTION

**Message**

The `function` code has a syntax error, or is not a valid `br`/`gz`/`lz` payload.

**Solution**

The [function](https://microlink.io/docs/api/parameters/function) parameter could not be read. Ensure your function:

- Has valid JavaScript syntax
- Uses proper function formatting (arrow function or regular function)
- Doesn't contain syntax errors like missing brackets or semicolons

When the code is sent compressed (`br#`, `gz#` or `lz#`), the payload also has to survive the URL intact: a truncated or re-encoded one cannot be decompressed. The `message` says which of the two happened.

## EINVALDATA

**Message**

The `data.<field>` has an invalid value (`<value>`). rule must be an object (or array of objects) with extraction options.

Example:

The `data.innerHTML` has an invalid value (empty). rule must be an object (or array of objects) with extraction options.

**Solution**

Use object rules for [data](https://microlink.io/docs/api/parameters/data) extraction instead of primitive values.

Valid:

- `data.title.selector=h1`
- `data.price.selector=.price&data.price.attr=text`
- `data.links.selectorAll=a&data.links.attr=href`

Invalid:

- `data.innerHTML=`
- `data.foo=html`
- `data.bar=false`

## EINVALQUERY

**Message**

The `<name>` query parameter is not allowed.

Example:

The `pdf.scale` query parameter must be between 0.1 and 2.

**Solution**

A query parameter was rejected. Drop it, or pass a value the API accepts.

Unknown [proxy.location](https://microlink.io/docs/api/parameters/proxy/location) country codes are also rejected.

## EINVALSTTL

**Message**

The `staleTtl` value is invalid.

**Solution**

The [staleTtl](https://microlink.io/docs/api/parameters/staleTtl) value should be a value less than the current [ttl](https://microlink.io/docs/api/parameters/ttl) provided.

## EINVALOVERLAYBG

**Message**

The gradient is not valid. Ensure it follows CSS gradient syntax.

**Solution**

The [overlay.background](https://microlink.io/docs/api/parameters/screenshot/overlay) value must be a valid CSS gradient or color. Common issues include:

- Missing color stops (e.g., `linear-gradient(90deg,)` instead of `linear-gradient(90deg, red, blue)`)
- Invalid color values
- Malformed gradient syntax

Ensure your gradient follows the [CSS gradient syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/gradient).

## EINTEGRATION

**Message**

You need a

PRO

plan for using integrations.

**Solution**

The [url](https://microlink.io/docs/api/parameters/url) provided targets a service the API resolves through a dedicated integration rather than a normal fetch, and those are available on paid plans only.

See [pricing](https://microlink.io/pricing) for upgrading your plan.

## EMAXREDIRECTS

**Message**

The target URL reached the maximum number of redirect after 10 times.

**Solution**

Ensure the [url](https://microlink.io/docs/api/parameters/url) provided reaches the destination URL in less than 10 hops.

## EPAGERANGE

**Message**

The `pdf.pageRanges` value is outside the target document.

**Solution**

The [pdf.pageRanges](https://microlink.io/docs/api/parameters/pdf/pageRanges) provided starts past the last page of the document, so there is nothing to render.

Request a range the document actually has, or drop the parameter to render all of it.

## EPDFTOOLARGE

**Message**

The target document is too large to render as a PDF within the time budget.

**Solution**

The [pdf](https://microlink.io/docs/api/parameters/pdf) rendering could not finish before the request [timeout](https://microlink.io/docs/api/parameters/timeout), even after splitting the document into parallel page ranges.

Reduce the amount of content to rasterize with a smaller [pdf.scale](https://microlink.io/docs/api/parameters/pdf), or split the source into shorter pages, and try again.

## EPRO

**Message**

The request has `x-api-key` header present and it has been performed against [api.microlink.io](https://api.microlink.io/) endpoint.

**Solution**

In order to [authenticate](https://microlink.io/docs/api/basics/authentication) your requests, you need to perform them against [pro.microlink.io](https://pro.microlink.io/). Check [endpoint](https://microlink.io/docs/api/basics/endpoint) to know more.

## EPROXY

**Message**

You need a

PRO

plan for using [proxy](https://microlink.io/docs/api/parameters/proxy) query parameter.

**Solution**

See [pricing](https://microlink.io/pricing) for upgrading your plan.

## EPROXYNEEDED

**Message**

The URL provided uses antibot protection. Upgrade to a

PRO

plan.

**Solution**

See [pricing](https://microlink.io/pricing) for upgrading your plan.

## ERATE

**Message**

Your daily rate limit has been reached. You need to wait or extend your plan.

**Solution**

You need to extend your [rate limit](https://microlink.io/docs/api/basics/rate-limit) quota or wait until you’re quota reset.

## ETIMEOUT

**Message**

The request reached maximum timeout.

**Solution**

When the target [url](https://microlink.io/docs/api/parameters/url) reached the [timeout](https://microlink.io/docs/api/parameters/timeout) associated with the request lifecycle, this error is thrown.

In order to avoid this error, the request should be resolved before timeout. The maximum is 30 seconds on the free endpoint and 60 seconds with an API key.

## EUNREACHABLE

**Message**

The URL did not respond after 9.5s.

**Solution**

The target [url](https://microlink.io/docs/api/parameters/url) sent no response within the time Microlink waited for it, and the message says how long that was. No status code came back: the host did not resolve, the connection did not open, or the server did not answer in time.

The request fails with HTTP status `424`. A [function](https://microlink.io/docs/api/parameters/function) that runs on the loaded page does not run, because there is no page to run it on. The response carries a `Retry-After` header in seconds. A target that does not answer is often down or throttling traffic for a while, so retrying immediately usually gets the same answer.

```js
importmqlfrom'@microlink/mql'

consturl='https://example.com'

try{

awaitmql(url)

}catch(error){

if(error.code!=='EUNREACHABLE')throwerror

constretryAfter=Number(error.headers['retry-after']??60)

// queue `url` again in `retryAfter` seconds

}
```

## ETTL

**Message**

You need a

PRO

plan for using [ttl](https://microlink.io/docs/api/parameters/ttl) query parameter.

**Solution**

See [pricing](https://microlink.io/pricing) for upgrading your plan.

## ESTTL

**Message**

You need a

PRO

plan for using [staleTtl](https://microlink.io/docs/api/parameters/staleTtl) query parameter.

**Solution**

See [pricing](https://microlink.io/pricing) for upgrading your plan.