JAYSON DERULO

1 files changed, 39 insertions, 0 deletions

diff --git a/errors.md b/errors.md
new file mode 100644
index 0000000..ecddc51
--- /dev/null
+++ b/errors.md
@@ -0,0 +1,39 @@
+# Errors
+
+[back to index](README.md)
+
+## Error Response Format
+
+All error responses follow the same shape:
+
+```json
+{
+    "message":"Session expired or invalid [request_id: 12346480868868238719]","success":false
+}
+```
+
+The `request_id` is always included at the end of the error message so you can look it up in the server logs aswell as being included in the message part so it is displayed to users/clients.
+The length of the request_id is capped at 32 Numbers and shouldnt be shorter than like 8)
+
+Some endpoints might include extra fields (like `endpoint` for toolkit errors or `results` for batch query errors) but `success` and `error` are always there.
+
+## Status Codes
+The following status codes (and what they mean) should be returned by JsonDerulo API compliant server 
+
+| Code | When                                                                                                           |
+|------|----------------------------------------------------------------------------------------------------------------|
+| 200  | everything worked and Json Derulo is happy                                                                     |
+| 400  | bad request, missing fields, invalid table or column names, too many WHERE conditions, etc.                    |
+| 401  | no token provided, token invalid or expired                                                                    |
+| 403  | you dont have permission (power level too low, IP not whitelisted, table access denied)                        |
+| 404  | toolkit not found or disabled, endpoint path doesnt exist                                                      |
+| 429  | rate limited, wait and try again                                                                               |
+| 500  | server error, database query failed, config reload failed, json derulo died                                    |
+| 502  | toolkit endpoint got an error from upstream (HTTP proxy mode)                                                  |
+| 503  | database is down, depressed or having a stroke                                                                 |
+
+## Notes
+
+- difference between 401 and 403: you get 401 when theres no valid session at all and you are trying to betray the jsonderulo server. 403 is when you have a session but your power (bottom) level or json's permissions dont allow the action.
+- 503 only happens when the server has detected database connectivity loss. Server shouldnt crash, but tells you the database is currently having a hissifit and will keep trying to reconnect and pass your request in the background.
+- batch query errors should be able to return partial results with a `results` array showing which sub queries succeeded and which failed.