Errors
Status codes and error response shapes.
Status codes
| Status | Meaning |
|---|---|
400 | Validation error — invalid input. Also a countryCode requests can't be routed from (unsupported_geography); see Proxies & geolocation. Also a request this destination can't be sent as given; see 400 — request the destination can't be sent. |
401 | Missing or invalid Authorization header. |
402 | Insufficient account balance. |
403 | Destination domain not enabled for your organization, or a path that needs KYC. See Access control & KYC. Also captureCookies on an account without it. |
429 | Your organization's rate limit exceeded. With errorType: "TargetFailingError", requests to this destination are failing right now instead; see A 429 about the destination. |
502 | The request could not be completed, or the destination's answer could not be returned to you. A destination's own 5xx page returns HTTP 200 instead; see Fetch. With errorType: "OriginRateLimitedError", the destination is rate-limiting requests; see Destination rate limiting. |
503 | A feature the request uses, such as XHR capture, is at capacity or temporarily unavailable, or no exit in the requested countryCode was available (geography_unavailable). Retry, after Retry-After seconds when that header is present. |
504 | The destination did not respond in time. See Failure classes. |
500 | Internal server error. |
One failure class does not appear in that table because it has no fixed status of its own: a
terminal origin failure is returned under whatever status the
destination itself answered with, including ones you will not otherwise see from us, such as 530.
Error response shape
Most errors return an ErrorResponse object:
{
"error": "Validation error",
"message": "URL protocol must be http or https",
"statusCode": 404,
"traceId": "…",
"issues": [{ "field": "url", "message": "URL protocol must be http or https" }]
}| Field | Description |
|---|---|
error | Error type identifier. |
message | Human-readable error message. |
statusCode | The status the destination returned, when the request reached it. Not the HTTP status of this response — read that from the response line. |
errorType | Machine-readable failure class. See Failure classes. |
traceId | Optional trace identifier. |
issues | Per-field validation issues (field, message). |
data | The destination's own response body, on the one failure class where that body is the answer. See Terminal origin failures. |
headers | The destination's own response headers. Present exactly when data is. |
Reading a failed fetch
Read two things, and do not confuse them:
- The HTTP status of our response says whose fault it is.
502and504mean the request failed upstream of us: the destination's answer could not be returned to you, it could not be reached, or it did not respond in time.500means something went wrong on our side. statusCodein the body is what the destination itself returned. It is also on thex-status-coderesponse header, the same header a successful fetch sets to the same value, so one read works either way. It is absent when we never got a response out of the destination — absent means "no response", not0.
{
"error": "Request failed",
"statusCode": 403,
"message": "The request to the destination failed"
}Sent with HTTP 502: the destination answered 403, and we could not return that answer to you.
Note that statusCode can be a success status. A destination that serves an anti-bot
challenge or a login wall as a 200 will report statusCode: 200 on a 502 — the response
came back, it just was not the content you asked for.
For a 4xx on the terminal-origin path, statusCode is also passed through as our HTTP status.
Key off statusCode and errorType, never off our HTTP status alone, which collapses distinct
upstream faults onto 502.
A 403 has two unrelated meanings
A body with reason means String refused the request: the destination domain is not enabled for your organization,
or the path needs KYC, and the reason says which. See Access control & KYC.
A body with error and message saying captureCookies is not enabled means the account doesn't have
captureCookies.
Anything else is the destination's own 403, passed through. A hostname that does not resolve is
never a 403: it returns 502 with errorType: "TargetHostNotFoundError".
Failure classes
errorType names the upstream failure when we can tell what it was. Use it to distinguish failure
classes that share the same HTTP status code.
errorType | What happened | What to do |
|---|---|---|
TargetCertificateError | The destination's TLS certificate cannot be verified. | See ignoreCertificateErrors. |
TooManyRedirectsError | The destination's redirect chain does not terminate. | The destination has to fix it; do not retry. |
TerminalOriginError | The destination's own configuration produced the answer. | Do not retry. Read data — see Terminal origin failures. |
TargetTimeoutError | The destination did not respond within our deadline. Sent with HTTP 504. | Retry later. |
TargetUnreachableError | We could not connect to the destination, or it dropped the connection before answering. The message names the network error, such as ERR_NAME_NOT_RESOLVED or ERR_CONNECTION_REFUSED. | Check the URL and that the site is up. Retry later for a transient error; a hostname that does not resolve will keep failing. |
TargetHostNotFoundError | The destination hostname has no DNS record. Sent with HTTP 502. | Check the hostname for typos; do not retry until it resolves. |
OriginRateLimitedError | The destination is rate-limiting requests. Sent with HTTP 502. | Back off and lower your request rate to this destination. See Destination rate limiting. |
TargetFailingError | Requests to this destination are failing for nearly everyone right now. Sent with HTTP 429 and a Retry-After header. | Retry this destination after Retry-After seconds. See A 429 about the destination. |
{
"error": "Request failed",
"message": "The destination did not respond within 60s",
"errorType": "TargetTimeoutError"
}TargetTimeoutError, TargetUnreachableError and TargetHostNotFoundError never carry statusCode,
because the destination never sent a response.
Destination rate limiting
When the destination itself is rate-limiting requests, the fetch returns HTTP 502 with
errorType: "OriginRateLimitedError":
{
"error": "Request failed",
"statusCode": 429,
"message": "The destination is rate-limiting requests. Back off and lower your request rate to this site.",
"errorType": "OriginRateLimitedError"
}Sent with HTTP 502 and x-status-code: 429. statusCode and x-status-code carry the status the destination
answered with. While a destination is rate-limiting, requests to it that time out return this error too,
without statusCode or x-status-code, because the destination never answered them.
This is the destination's limit, not your organization's rate limit: a higher plan doesn't raise it, and it works the same way for every destination. Back off, lower your request rate to that destination, then retry the requests that failed. Other destinations are not affected.
A 429 about the destination
A 429 is your organization's rate limit unless its body carries
errorType: "TargetFailingError" or errorType: "TargetRequestLimitError".
The destination is failing
{
"error": "Rate limit exceeded",
"message": "Too many requests to this destination. Retry after 12.4 s.",
"retryAfterMs": 12400,
"errorType": "TargetFailingError"
}That 429 means requests to this destination are failing for nearly everyone right now. Retry this destination after
Retry-After seconds; Retry-After-Ms and retryAfterMs give the same wait in milliseconds. Your organization's rate
limit is unaffected, and requests to other destinations go through as usual.
The destination's request limit
errorType: "TargetRequestLimitError" means requests to this destination are over the rate String sends to it, and
this one was refused before it reached the destination. When the limit is your organization's own rate for that
destination, the response names it:
X-RateLimit-Scope: destination-org
X-RateLimit-Limit-Rps: 10
X-RateLimit-Burst: 20{
"error": "Rate limit exceeded",
"message": "Your requests to www.example.com are limited to 10 per second, with bursts of up to 20, to keep the site reachable. Lower your request rate to this site.",
"errorType": "TargetRequestLimitError"
}Otherwise the response carries no rate headers, and its message reads
Internal rate limit for www.example.com reached. Lower your request rate to this site.
Neither sends Retry-After. Lower your request rate to that destination, to at most X-RateLimit-Limit-Rps on
average with no more than X-RateLimit-Burst at once when they are given, instead of retrying each refused request on
a timer. Your organization's rate limit is unaffected, and requests to other destinations go through as usual.
| Response | Whose limit | What to do |
|---|---|---|
429 with limitRequestsPerSecond | Your organization's | Lower your overall request rate. See Handling 429s. |
429 with errorType: "TargetFailingError" | No limit: that destination is failing | Retry that destination after Retry-After seconds. |
429 with errorType: "TargetRequestLimitError" | String's limit for that destination | Lower your request rate to that destination. |
502 with errorType: "OriginRateLimitedError" | The destination's | Back off and lower your request rate to that destination. |
A destination's own 5xx page is not a failed fetch: it returns HTTP 200 with the destination's status in
statusCode. See Fetch.
Terminal origin failures
TerminalOriginError marks a response the destination's own configuration decided: a private object, a hostname whose
DNS no longer resolves, a certificate the destination never finished installing. Retrying the same request gets the
same answer.
Two families produce it:
- Object-store denials. A private object, or a signed URL whose signature has expired or was
built wrong, answering
AccessDenied. - Cloudflare origin errors. The edge is up and the origin behind it is not:
1000–1004,1013,1016and1018(DNS and hostname misconfiguration), and525/526(the origin's TLS).
This is the one failure class whose shape differs from the rest of this page. Our HTTP status is
the destination's own status rather than 502, and the body carries the destination's response
verbatim:
{
"error": "Request failed",
"statusCode": 403,
"message": "The destination answered in a way that will not change on retry; its response is included.",
"errorType": "TerminalOriginError",
"data": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error><Code>AccessDenied</Code><Message>Access Denied</Message></Error>",
"headers": { "content-type": "application/xml", "server": "AmazonS3" }
}Sent with HTTP 403 — the destination's status, also on x-status-code. A Cloudflare 1016 arrives
the same way under HTTP 530, carrying that error page in data.
So the rule higher up this page — that our HTTP status only tells you whose fault it is — has one
exception here, and it is the useful kind: the status is the destination's, and data is its own
explanation of why. Read data and act on what the destination said. The remedy is almost always on
its side: the object is private, the signed URL expired, the domain no longer resolves.
Always a JSON envelope
Like every error on this page, this one is returned as JSON whatever format you requested, so a
format: "raw" request receives this envelope rather than raw bytes.
Common cases
400 — validation
{
"error": "Validation error",
"message": "GET requests cannot have a body",
"issues": [{ "field": "body", "message": "GET requests cannot have a body" }]
}400 — request the destination can't be sent
{
"error": "Request failed",
"message": "This destination can't be sent the request's cookies (sessionid). Send the request without them, or contact [email protected] to have them allowed for this site."
}The input is valid, but part of it can't be sent to this destination. message names what to remove or
change. Retrying the same request returns the same error.
A site can be sent only the cookies approved for it. To send another cookie, email [email protected] with the site and the cookie names to have them allowed for that site.
401 — authentication
{ "error": "Missing or invalid Authorization header" }402 — insufficient balance
{ "error": "Credits exceeded" }Branch on the 402 status, not the error text.
403 — destination not enabled
{ "reason": "Requests to example.com are not allowed. Contact [email protected] for access." }A path that needs KYC returns the same status with its own reason. See
Access control & KYC.
403 — captureCookies not enabled
{
"error": "Request failed",
"message": "captureCookies is not enabled for your account. Contact [email protected] to have it turned on."
}captureCookies is an Enterprise feature, enabled per
account. Send the request without it, or contact [email protected] to have it enabled.