String docs

Errors

Status codes and error response shapes.

Status codes

StatusMeaning
400Validation 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.
401Missing or invalid Authorization header.
402Insufficient account balance.
403Destination domain not enabled for your organization, or a path that needs KYC. See Access control & KYC. Also captureCookies on an account without it.
429Your organization's rate limit exceeded. With errorType: "TargetFailingError", requests to this destination are failing right now instead; see A 429 about the destination.
502The 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.
503A 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.
504The destination did not respond in time. See Failure classes.
500Internal 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" }]
}
FieldDescription
errorError type identifier.
messageHuman-readable error message.
statusCodeThe status the destination returned, when the request reached it. Not the HTTP status of this response — read that from the response line.
errorTypeMachine-readable failure class. See Failure classes.
traceIdOptional trace identifier.
issuesPer-field validation issues (field, message).
dataThe destination's own response body, on the one failure class where that body is the answer. See Terminal origin failures.
headersThe 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. 502 and 504 mean 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. 500 means something went wrong on our side.
  • statusCode in the body is what the destination itself returned. It is also on the x-status-code response 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", not 0.
{
  "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.

errorTypeWhat happenedWhat to do
TargetCertificateErrorThe destination's TLS certificate cannot be verified.See ignoreCertificateErrors.
TooManyRedirectsErrorThe destination's redirect chain does not terminate.The destination has to fix it; do not retry.
TerminalOriginErrorThe destination's own configuration produced the answer.Do not retry. Read data — see Terminal origin failures.
TargetTimeoutErrorThe destination did not respond within our deadline. Sent with HTTP 504.Retry later.
TargetUnreachableErrorWe 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.
TargetHostNotFoundErrorThe destination hostname has no DNS record. Sent with HTTP 502.Check the hostname for typos; do not retry until it resolves.
OriginRateLimitedErrorThe destination is rate-limiting requests. Sent with HTTP 502.Back off and lower your request rate to this destination. See Destination rate limiting.
TargetFailingErrorRequests 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.

ResponseWhose limitWhat to do
429 with limitRequestsPerSecondYour organization'sLower your overall request rate. See Handling 429s.
429 with errorType: "TargetFailingError"No limit: that destination is failingRetry that destination after Retry-After seconds.
429 with errorType: "TargetRequestLimitError"String's limit for that destinationLower your request rate to that destination.
502 with errorType: "OriginRateLimitedError"The destination'sBack 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, 1016 and 1018 (DNS and hostname misconfiguration), and 525/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.