From ea266f1b80bbad0d4056b7d89c1603e9f91c6d87 Mon Sep 17 00:00:00 2001
From: Tim Abbott <tabbott@zulipchat.com>
Date: Mon, 16 Apr 2018 15:42:34 -0700
Subject: [PATCH] /api: Expand "common errors" page to more generally cover
 error handling.

---
 templates/zerver/api/common-error-payloads.md | 21 ----------
 templates/zerver/api/rest_error_handling.md   | 38 +++++++++++++++++++
 templates/zerver/api/sidebar.md               |  5 +--
 3 files changed, 39 insertions(+), 25 deletions(-)
 delete mode 100644 templates/zerver/api/common-error-payloads.md
 create mode 100644 templates/zerver/api/rest_error_handling.md

diff --git a/templates/zerver/api/common-error-payloads.md b/templates/zerver/api/common-error-payloads.md
deleted file mode 100644
index 70aa742b18..0000000000
--- a/templates/zerver/api/common-error-payloads.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Sample payloads for common errors
-
-## Invalid API key
-
-A typical failed JSON response for when the API key is invalid:
-
-{generate_code_example|invalid-api-key|fixture}
-
-## Missing request argument(s)
-
-A typical failed JSON response for when a required request argument
-is not supplied:
-
-{generate_code_example|missing-request-argument-error|fixture}
-
-## User not authorized for query
-
-A typical failed JSON response for when the user is not authorized
-for a query:
-
-{generate_code_example|user-not-authorized-error|fixture}
diff --git a/templates/zerver/api/rest_error_handling.md b/templates/zerver/api/rest_error_handling.md
new file mode 100644
index 0000000000..64b1ba1961
--- /dev/null
+++ b/templates/zerver/api/rest_error_handling.md
@@ -0,0 +1,38 @@
+# Error Handling
+
+Zulip's API will always return a JSON format response.  Like any good
+API, the HTTP status code indicates whether the request was successful
+(200 = success, 40x = user error, 50x = server error).  Every response
+will contain at least two keys: `msg` (a human-readable error message)
+and `result`, which will be either `error` or `success` (this is
+redundant with the HTTP status code, but is convenient when printing
+responses while debugging).
+
+For some common errors, Zulip provides a `code` attribute.  Where
+present, clients should check `code`, rather than `msg`, when looking
+for specific error conditions, since the `msg` strings are
+internationalized (e.g. the server will send the error message
+translated into French if the user has a French locale).
+
+Each endpoint documents its own unique errors; below, we document
+errors common to many endpoints:
+
+## Invalid API key
+
+A typical failed JSON response for when the API key is invalid:
+
+{generate_code_example|invalid-api-key|fixture}
+
+## Missing request argument(s)
+
+A typical failed JSON response for when a required request argument
+is not supplied:
+
+{generate_code_example|missing-request-argument-error|fixture}
+
+## User not authorized for query
+
+A typical failed JSON response for when the user is not authorized
+for a query:
+
+{generate_code_example|user-not-authorized-error|fixture}
diff --git a/templates/zerver/api/sidebar.md b/templates/zerver/api/sidebar.md
index 9f20e9adc8..81a9d482af 100644
--- a/templates/zerver/api/sidebar.md
+++ b/templates/zerver/api/sidebar.md
@@ -18,6 +18,7 @@
 
 * [Installation instructions](/api/installation-instructions)
 * [API keys](/api/api-keys)
+* [Error handling](/api/rest_error_handling)
 
 #### Messages
 
@@ -45,7 +46,3 @@
 * [Register a queue](/api/register-queue)
 * [Get events from queue](/api/get-events-from-queue)
 * [Delete a queue](/api/delete-queue)
-
-#### Common Errors
-
-* [Example payloads](/api/common-error-payloads)