EnConvert API Error Codes#

This reference lists the HTTP status codes and error messages the EnConvert API returns, from 200 OK for synchronous conversions and 202 Accepted for async and batch jobs to the error responses documented below. Each error section lists the exact message strings, the condition that triggers each one, and how to fix the request. Error bodies do not all have the same shape: there are six, and the Error response format section shows each one.

A job that fails after it was accepted is not an HTTP error. The 202 stands and the failure appears in the job's status payload when you poll it, described in Sync and async jobs.

HTTP Status Codes#

Error Response Format#

Six body shapes exist. Which one you get depends on where the failure happened, not on the status code alone, so check the type of detail before you read it.

1. String detail. The common case, and the only shape most integrations see.

{
    "detail": "Authentication required"
}

2. Object detail. The plan file-size 413. The structured object is the value of detail, so read body.detail.max_size, not body.max_size. See 413 Payload Too Large.

{
    "detail": {
        "error": "File too large",
        "file_size": 10485760,
        "max_size": 5242880,
        "tier": "free",
        "key_type": "private"
    }
}

3. Array detail plus errors. Schema validation (422) returns both: detail is the raw validator output, errors is a parallel array of human-readable strings. See 422 Unprocessable Entity.

4. Typed conversion envelope. {"error", "code", "detail"}, with a machine-readable code. Emitted only by the three V1 URL conversion endpoints. See Browser conversion errors.

5. Unhandled exception. A 500 that did not come from a converter has no detail at all:

{
    "error": "Internal server error",
    "event_id": "a1b2c3d4"
}

6. Gateway request timeout. The gateway's own 300-second budget produces a 504 with no detail and no code:

{
    "error": "Request timeout"
}

400 Bad Request#

Returned when the request contains invalid parameters, missing fields, or malformed data.

Input Validation#

Batch and Mode Validation#

Auth, Cookies & Headers Validation#

URL Safety (SSRF)#

Every URL-based endpoint screens the target url before fetching it. These messages are returned as 400 when the URL is not a public http(s) address.

Render Option Validation#

Sitemap and Crawl Errors#

Conversion Content Errors#

401 Unauthorized#

Returned when authentication is missing or invalid.

402 Payment Required#

Returned when a usage limit is exceeded. The split between 402 and 403 is not symmetric, and it catches people out. Every quota condition answers 402, and so does a V2 endpoint that is switched off on your plan. V1 feature gates answer 403 (async, webhooks, ZIP output, basic auth, batch). Rate limiting is a separate mechanism that answers 429, never 402.

Running out of monthly AI credits does not produce a 402. Schema extraction falls back to the heuristic and CSS result and the request still succeeds. Allowances, prices and what counts as one operation are in Rate limits and quotas.

403 Forbidden#

Returned when access is denied due to key type, domain, V1 plan feature, or endpoint restrictions. V2 endpoint gates are the exception: they answer 402, not 403.

API Key and Token Restrictions#

Plan Feature Restrictions#

Widget Restrictions#

Two more 403 messages are about neither keys nor plans: Account suspended, returned for every request once the account behind the key or token is suspended, and robots.txt disallows fetching this URL (request sent respect_robots=true)., returned by perceive when you asked for robots compliance and the target disallows the path.

404 Not Found#

409 Conflict#

410 Gone#

The artifact existed but has passed your plan's file-retention window and is no longer in storage. Retention is per plan; see Rate limits and quotas.

Treat 410 as final for that object. Re-running the request produces a fresh artifact; retrying the download does not.

413 Payload Too Large#

Returned when the uploaded file exceeds the plan's maximum file size.

{
    "detail": {
        "error": "File too large",
        "file_size": 10485760,
        "max_size": 5242880,
        "tier": "free",
        "key_type": "private"
    }
}

The limit is checked against the uploaded part's exact byte count before any conversion work starts. A file whose size is exactly max_size is accepted; only a larger file is rejected. The Content-Length header is a fallback for older call sites that do not hand their upload object to the check.

POST /v2/ingest/files does not use this shape. It answers 413 with a plain string detail: File '{filename}' exceeds the {max_size}-byte limit.

Per-plan ceilings are listed in Rate limits and quotas, and the upload paths this applies to are in File ingestion.

Browser Conversion Errors (415 / 422 / 502 / 504)#

URL conversions distinguish a fault in the target site or the input (a 4xx, 502, or 504 you can act on) from a fault in our engine (a 500). The three V1 URL conversion endpoints (url-to-pdf, url-to-screenshot, url-to-markdown) return these typed failures with a machine-readable code alongside detail:

{
    "error": "Gateway Timeout",
    "code": "upstream_timeout",
    "detail": "The target site took too long to respond while rendering PDF for https://example.com."
}

Those five are the whole vocabulary. No other endpoint family emits a code, V2 included: a V2 failure comes back as a plain detail string. The envelope's base class defines a sixth slug, conversion_error, but nothing raises it, so it never reaches you. Branch on the five above and treat any other value as unknown.

A 504 can also arrive in two untyped shapes: {"error": "Request timeout"} when the request outlives the gateway's 300-second budget, and a plain string detail carrying the timeout message when a document conversion (LibreOffice) times out. Neither carries a code.

422 Unprocessable Entity#

Schema validation failures return two parallel arrays. detail is the raw validator output, which is what you map back to form fields. errors is one human-readable string per problem, which is what you show a user.

{
    "detail": [
        {
            "loc": ["body", "max_pages"],
            "msg": "Input should be a valid integer, unable to parse string as an integer",
            "type": "int_parsing"
        }
    ],
    "errors": [
        "body.max_pages: Input should be a valid integer, unable to parse string as an integer (you sent 'ten')"
    ]
}

Three type values are worth handling by name:

A 422 with a selector_not_found code is a different thing: a render precondition that failed, covered in Browser conversion errors.

429 Too Many Requests#

Rate limiting is a short-window fairness control and is separate from the monthly ops allowance. Exhausting the allowance answers 402; only the rate limiter answers 429.

A 429 carries four headers:

These headers appear on the 429 only. Successful responses carry no rate-limit headers and no remaining-ops headers, so you cannot read your remaining budget off a response; check usage in the dashboard. See Rate limits and quotas.

500 Internal Server Error#

Anything that faults outside a converter never reaches you as text. It comes back without a detail at all:

{
    "error": "Internal server error",
    "event_id": "a1b2c3d4"
}

One case surprises people: a malformed JSON body sent to a V1 URL endpoint (url-to-pdf, url-to-screenshot, url-to-markdown, website-to-pdf, website-to-screenshot) returns this 500 rather than a 422, because those endpoints read the raw body. The same malformed body on a V2 endpoint returns a 422 with type: json_invalid.

If you encounter persistent 500 errors, the issue is likely with the input file or URL. Try with a different input to isolate the problem.

503 Service Unavailable#

Two different capacity gates exist and they ask for different waits, so read Retry-After instead of assuming one. These errors are otherwise transient: retry after a short delay.

V2 endpoint errors#

The V2 web intelligence endpoints reuse the status codes above, with a few V2-specific conditions worth calling out.

Quota and plan (402 / 403)#

V2 operations meter against the same unified monthly ops allowance as V1 conversions: one op per unit of work. Any paid plan with overage enabled lets you run past the allowance ($0.02/op); otherwise the cap is hard.

Two V2 behaviours are deliberately not errors. Exhausting the AI-credit balance does not fail the request: schema extraction falls back to the heuristic and CSS result. And a multi-URL distill run that crosses the ops boundary part-way does not 402 either: it stops there, returns the URLs it finished, and appends a warning naming how many were skipped.

Validation (422)#

Every V2 request schema rejects unknown keys, so a misspelled parameter is a 422 naming the field. The body shape is described under 422 Unprocessable Entity.

Search provider (502 / 503)#

The lookup endpoint depends on an upstream search provider. Raw provider error text never reaches the client.

Not found (404)#

GET and DELETE on a V2 operation_id, job_id, or watcher_id that does not exist, or that belongs to a different project, returns 404. Existence is never leaked across projects.

Accepted (202)#

Ingest is always asynchronous: POST /v2/ingest answers 202 with a job_id you poll. Perceive batches larger than 10 URLs answer 202 with status queued. A batch of 10 or fewer normally answers inline, but if it outruns the inline window it degrades to 202 with status processing and a warning, so handle 202 on any batch size.

A 202 also means later failures are not HTTP errors. Poll the job and read its status payload, as described in Sync and async jobs.

Troubleshooting#

Authentication Issues#

• Getting 401? Check that your API key is valid and active in the dashboard. If using JWT, ensure the token hasn't expired (1-hour lifetime).
• Getting 403 about browser usage? You're using a private key (sk_...) from client-side code. Switch to a public key with JWT for browser-based requests.
• Getting 403 about domain? Add your domain to the API key's allowed domains list in the dashboard.

Conversion Issues#

• Getting 400 about file format? Ensure the uploaded file extension matches the endpoint (e.g., .json for json-to-xml, .docx for doc-to-pdf).
• Getting 413? Your file exceeds the plan's size limit. Read detail.max_size from the response, then check your plan's max file size or upgrade.
• Getting 402? You've hit your monthly ops allowance, the watcher cap, or the storage limit, or the project has no active billing period. Check usage in the dashboard and see Rate limits and quotas.

Feature Access Issues#

• Getting 403 about plan features? The V1 feature you're trying to use (async, batch, webhooks, ZIP output, basic auth) requires a higher plan tier. Check the plan feature table.
• Getting 402 on a V2 endpoint that isn't about quota? V2 endpoint gates answer 402, not 403. The message reads ... is not available on your current plan. Upgrade to a V2-inclusive plan to access this endpoint.

Frequently asked questions#

Why does the API return 402 Payment Required for a file conversion?#

A 402 means a usage limit is exhausted: your unified monthly ops allowance (500 ops on the Founding plan), the active-watcher cap, or your project's storage allocation. It also covers two non-quota cases: a project with no active billing period, and a V2 endpoint that is switched off on your plan. Batch requests that would exceed the remaining monthly ops allowance are rejected upfront with a 402 for the entire batch. V1 conversions and V2 operations draw from the same allowance; any paid plan with overage enabled ($0.02/op) lets you run past it. Rate limiting is a different mechanism and answers 429.

How do I fix a 401 Unauthorized error from the conversion API?#

Check that the API key is present, starts with sk_ or pk_, and is still active in the dashboard, since revoked keys return API Key revoked. If you authenticate with a JWT, note that access tokens expire after 1 hour (Token has expired) and refresh tokens after 7 days.

Why am I getting 413 Payload Too Large when uploading a file?#

The uploaded file exceeds your plan's maximum file size, measured from the uploaded part's exact byte count before any conversion work starts. A file exactly at the limit is accepted. The 413 body nests a structured object under detail, with file_size, max_size (both in bytes), tier, and key_type, so read it as detail.max_size rather than as a top-level field.

Can I use a private API key from browser JavaScript?#

No. A private key (sk_...) used in a request with a browser Origin header returns 403 Private API keys cannot be used from browsers. Exchange a public key for a JWT at /v1/auth/token and use that token for browser-based API calls.

Is a 503 Service Unavailable error from the API permanent?#

No, 503 errors such as Converter not available: {endpoint} or Turnstile verification unavailable are typically transient. Retry the request after a short delay.