📘 תיעוד 27

תגובות שגיאה

עודכן לאחרונה: 5 במאי 2026 | הצגה כ-Markdown | הגדרת סוכן

כאשר Cloudflare לא יכולה להשלים בקשה, היא יוצרת תגובת שגיאה. הפורמט תלוי במה שהלקוח מבקש דרך כותרת Accept ובתצורת Custom Errors של האזור (zone).

כברירת מחדל, תגובות השגיאה הן HTML. לקוחות שמבקשים פורמט מובנה (כמו application/json, application/problem+json, או text/markdown) מקבלים במקום זאת תגובה קריאה למכונה. התגובה הקריאה למכונה מכסה את כל קודי השגיאה 1xxx (שמחזירים קודי מצב HTTP 4xx או 5xx לפי השגיאה) ואת שגיאות 5xx ש-Cloudflare יוצרת (500, 502, 504, 520-526). תגובות לשגיאות 5xx ששרת המקור יצר מועברות על ידי Cloudflare אל הלקוח ואינן מושפעות.

הערה

הדף הזה עוסק בפורמט של תגובות שגיאה ש-Cloudflare יוצרת. להמרת תוכן של דף מקור ל-Markdown, ראו Markdown for Agents. להחלפת דפי שגיאה ברירת מחדל בתוכן מותאם, ראו Custom Errors.

#משא ומתן על תוכן

Cloudflare בוחרת את פורמט התגובה לפי כותרת Accept של הלקוח, לפי משא ומתן על תוכן ב-HTTP הרגיל. כאשר כמה פורמטים קבילים, גורמי איכות (ערכי q) קובעים את הקדימות. באותו ערך איכות, הסוג שמופיע ראשון מנצח.

תגובות שגיאה מובנות זמינות בכל התוכניות, כולל התוכנית החינמית. Custom Error Rules לדריסת התגובות האלה דורשות תוכנית בתשלום של Cloudflare.

#אינטראקציה עם Custom Errors

תגובות שגיאה מובנות הן ברירת המחדל לאזורים בלי תצורת שגיאה מותאמת. אזורים שמשתמשים ב-Custom Errors שומרים על שליטה מלאה במה שהלקוחות מקבלים.

מה שהלקוח מקבל תלוי באילו תכונות שגיאה מותאמת הוגדרו באזור. ראו את הסעיפים הבאים לפרטים.

#בלי דף שגיאה מותאם, בלי כללי שגיאה מותאמים

זו ברירת המחדל ברוב האזורים. Cloudflare מגישה את תגובת השגיאה ברירת המחדל שלה בפורמט שהלקוח מבקש.

#דף שגיאה מוגדר, בלי כללי שגיאה מותאמים

לאזור יש Error Page שהועלה דרך לוח הבקרה של Cloudflare. לא הוגדרו Custom Error Rules. ה-Error Page מוגש לכל הלקוחות בלי קשר לכותרת Accept. דפי Error Page לא מבצעים משא ומתן על תוכן.

אם אתם רוצים שסוכנים יקבלו תגובות מובנות ועדיין לשמור את ה-HTML המותאם לדפדפנים, הוסיפו Custom Error Rule שמתאים על כותרת Accept. ראו את הסעיף הבא לפרטים.

#Custom Error Rules מוגדרים

לאזור יש כלל אחד או יותר של Custom Error Rules (זמינים בתוכניות בתשלום). אלה מקבלים עדיפות על פני Error Pages. אתם שולטים במה שמוגש, למי, ובאילו תנאים.

Custom Error Rules יכולים להתאים על כל כותרת בקשה, כולל Accept, ויכולים לכוון לקודי שגיאה מסוימים. אפשר להגיש JSON ללקוחות API, Markdown לסוכנים, ו-HTML לדפדפנים, הכל מאותו אזור.

דוגמה: הגשת JSON מותאם ללקוחות API בשגיאה 522

Custom Error Rule הזה תואם לשגיאות 522 שבהן הלקוח מבקש JSON:

ביטוי: (http.response.code eq 522) and (any(http.request.headers["accept"][*] contains "application/json"))

פעולה: הגשת תגובת JSON מותאמת עם פורמט השגיאה שלכם.

הכלל הזה מקבל עדיפות גם על תגובת ה-JSON המובנית ברירת המחדל וגם על כל Error Page שהוגדר. לקוחות שלא תואמים לכלל (לדוגמה, דפדפנים שמבקשים HTML) נופלים אל ה-Error Page או אל תגובת ברירת המחדל של Cloudflare.

דוגמה: הגשת תגובות מובנות לסוכנים ודף HTML מותאם לדפדפנים

אם לאזור יש Error Page מוגדר, הוא מוגש לכל הלקוחות, כולל סוכנים שמבקשים JSON או Markdown. כדי לאפשר לסוכנים לקבל את התגובות המובנות ברירת המחדל של Cloudflare, הסירו את ה-Error Page. בלי Error Page, Cloudflare מכבדת את כותרת Accept באופן אוטומטי: סוכנים מקבלים JSON או Markdown מובנים, ודפדפנים מקבלים HTML.

אם צריך לשמור את ה-Error Page לדפדפנים אבל להגיש תוכן מובנה מותאם לסוכנים, צרו Custom Error Rules שמתאימים על כותרת Accept ומגישים תוכן JSON או Markdown משלכם. דפדפנים שלא תואמים לאף אחד מהכללים ממשיכים לקבל את Error Page ה-HTML המותאם שלכם.

#סדר עדיפות

כאשר Cloudflare יוצרת תגובת שגיאה, סדר העדיפות הבא קובע מה הלקוח מקבל:

1. Custom Error Rules: אם כלל תואם לשגיאה ולתנאי הבקשה, מוגש התוכן של הכלל.
2. Error Pages: אם Error Page מוגדר לסוג השגיאה ואף Custom Error Rule לא תאם, ה-Error Page מוגש כ-HTML בלי קשר לכותרת Accept.
3. תגובות שגיאה מובנות: אם אף Custom Error Rule לא תאם ולא הוגדר Error Page, Cloudflare מגישה את תגובת ברירת המחדל שלה בפורמט שהלקוח ביקש (JSON, Markdown, או HTML).

לסדר העדיפות המלא, כולל כללים ברמת החשבון מול כללים ברמת האזור, תגובות חסימה מותאמות של WAF, ודפי אתגר אבטחה, ראו את התיעוד של Custom Errors.

#דוגמאות

#JSON: 522 Connection timed out

{
	"type": "https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/error-522/",
	"title": "Error 522: Connection timed out",
	"status": 522,
	"detail": "Cloudflare could not establish a TCP connection to the origin server. The TCP handshake timed out, which may indicate the origin is overloaded, firewalling Cloudflare, or unreachable at the network level.",
	"instance": "9f140b785e57c458",
	"error_code": 522,
	"error_name": "connection_timeout",
	"error_category": "origin",
	"ray_id": "9f140b785e57c458",
	"timestamp": "2026-04-24T09:22:40Z",
	"zone": "example.com",
	"cloudflare_error": true,
	"retryable": true,
	"retry_after": 120,
	"owner_action_required": true,
	"what_you_should_do": "**Wait and retry.** Back off for at least 120 seconds. If the error persists, the website operator should verify firewall rules and ensure the origin accepts connections from Cloudflare IP ranges.",
	"footer": "This error was generated by Cloudflare on behalf of the website owner."
}

#Markdown: 522 Connection timed out

---
error_code: 522
error_name: connection_timeout
error_category: origin
status: 522
ray_id: 9f140b785e57c458
timestamp: 2026-04-24T09:22:40Z
zone: example.com
cloudflare_error: true
retryable: true
retry_after: 120
owner_action_required: true
---

# Error 522: Connection timed out

## What Happened

Cloudflare could not establish a TCP connection to the origin server. The TCP handshake timed out, which may indicate the origin is overloaded, firewalling Cloudflare, or unreachable at the network level.

## What You Should Do

**Wait and retry.** Back off for at least 120 seconds. If the error persists, the website operator should verify firewall rules and ensure the origin accepts connections from Cloudflare IP ranges.

---

This error was generated by Cloudflare on behalf of the website owner.

#בדיקת תגובות שגיאה מובנות

שליפת תגובת ה-JSON המובנית לשגיאה 522:

curl --silent --compressed --header "Accept: application/json" \
  --user-agent "TestAgent/1.0" --header "Accept-Encoding: gzip, deflate" \
  "https://example.com/cdn-cgi/error/522" | jq .

שליפת תגובת ה-Markdown המובנית:

curl --silent --compressed --header "Accept: text/markdown" \
  --user-agent "TestAgent/1.0" --header "Accept-Encoding: gzip, deflate" \
  "https://example.com/cdn-cgi/error/522"

בדיקה של כותרת Retry-After בשגיאה שאפשר לנסות שוב:

curl --silent --compressed --dump-header - --output /dev/null \
  --header "Accept: application/json" --user-agent "TestAgent/1.0" \
  --header "Accept-Encoding: gzip, deflate" \
  "https://example.com/cdn-cgi/error/521" | grep -i retry-after

#שדות התגובה

גם תגובות JSON וגם תגובות Markdown מכילות את אותה קבוצת שדות. תגובות JSON מחזירות אותם כאובייקט שטוח. תגובות Markdown שמות אותם ב-frontmatter של YAML ואחריו מקטעי פרוזה. הגדרות השדות למטה חלות על שני הפורמטים.

תגובות JSON עוקבות אחרי RFC 9457 (Problem Details for HTTP APIs). כל לקוח HTTP שמבין Problem Details יכול לנתח את חמשת האיברים הסטנדרטיים (type, title, status, detail, instance) בלי קוד ייחודי ל-Cloudflare.

#איברים סטנדרטיים של RFC 9457

#איברי הרחבה של Cloudflare

#מבנה ייחודי ל-Markdown

תגובות Markdown שמות את השדות האלה ב-frontmatter של YAML (בין מפרידי ---), ואחריהם שלושה מקטעי פרוזה:

• # Error {code}: {description}: כותרת עם קוד השגיאה ותיאור קצר.
• ## What Happened: מתאים לשדה detail.
• ## What You Should Do: מתאים לשדה what_you_should_do.

ה-frontmatter משמיט את האיברים הסטנדרטיים של RFC 9457 (type, title, instance) ואת השדה footer, כי אלה או מיותרים ביחס לפרוזה או לא חלים על פורמט Markdown.

#קטגוריות שגיאה

השדה error_category מסווג את התקלה כדי שלקוחות יוכלו לנתב התנהגות של ניסיון חוזר והסלמה בלי לנתח את שדות הפרוזה.

#קטגוריות שגיאה 5xx

#קטגוריות שגיאה 1xxx

#כותרת Retry-After

קודי שגיאה שאפשר לנסות שוב כוללים כותרת תגובת HTTP סטנדרטית Retry-After. ערך הכותרת בשניות תואם לשדה retry_after בגוף התגובה.

#ערכי Retry-After עבור 5xx

קודים שלא ניתן לנסות שוב (525, 526) לא כוללים את כותרת Retry-After.

#ערכי Retry-After עבור 1xxx

שישה קודי שגיאה 1xxx שניתן לנסות שוב פולטים Retry-After:

כל שאר קודי השגיאה 1xxx לא ניתנים לניסיון חוזר ולא כוללים את כותרת Retry-After.

אם כלל הגבלת קצב של WAF כבר הגדיר ערך Retry-After דינמי על התגובה, הערך הזה מקבל עדיפות על ברירת המחדל.

#משאבים נוספים

• שגיאות Cloudflare 1xxx
• שגיאות Cloudflare 5xx
• Custom Errors
• מגבלות חיבור
• Markdown for Agents (המרת תוכן)
• RFC 9457, Problem Details for HTTP APIs