Add docs on rate limits and status codes

docs/guides/fundamentals/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Fundamentals",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Core technical details about how the Anytype API works."
+  }
+}

docs/guides/fundamentals/rate-limits.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 1
+title: "Rate Limits"
+description: "Understanding rate limits and how to handle them when using the Anytype API."
+keywords: [anytype, api, rate limits, throttling, best practices]
+---
+
+# Rate Limits
+
+The Anytype API implements rate limiting as a guardrail to protect your local Anytype instance from being overwhelmed by too many requests. Since the API runs on your own resources, these limits help ensure stable operation.
+
+## Rate Limit Configuration
+
+The API uses **burst rate limiting**:
+
+| Parameter | Value |
+|-----------|-------|
+| Sustained rate | 1 request per second |
+| Burst size | 60 requests |
+
+This means you can send up to 60 requests in quick succession (burst), after which requests are limited to 1 per second until the burst capacity recovers.
+
+## Disabling Rate Limits
+
+You can disable rate limiting by setting the following environment variable before starting Anytype:
+
+```bash
+ANYTYPE_API_DISABLE_RATE_LIMIT=1
+```
+
+## Rate Limit Errors
+
+When you exceed the rate limit, the API returns a `429` status code with the following response:
+
+```json
+{
+  "code": "rate_limit_exceeded",
+  "message": "Rate limit exceeded",
+  "object": "error",
+  "status": 429
+}
+```

docs/guides/fundamentals/status-codes.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 2
+title: "Status Codes"
+description: "HTTP status codes returned by the Anytype API."
+keywords: [anytype, api, status codes, errors, http]
+---
+
+# Status Codes
+
+The Anytype API uses standard HTTP status codes to indicate the success or failure of requests.
+
+## Success Codes
+
+| HTTP Status | Description |
+|:------------|:------------|
+| 200 | The request was successful. |
+| 201 | A new resource was created. |
+
+## Error Codes
+
+Error responses include a JSON body with additional details:
+
+```json
+{
+  "code": "error_code",
+  "message": "Human-readable error message",
+  "object": "error",
+  "status": 400
+}
+```
+
+| HTTP Status | `code` | Description |
+|:------------|:-------|:------------|
+| 400 | `bad_request` | The request body is invalid or malformed. |
+| 401 | `unauthorized` | The API key is missing or invalid. |
+| 403 | `forbidden` | The API key doesn't have permission for this operation. |
+| 404 | `object_not_found` | The requested resource does not exist. |
+| 410 | `resource_gone` | The resource has been deleted. |
+| 429 | `rate_limit_exceeded` | Too many requests. See [Rate Limits](./rate-limits.md). |
+| 500 | `internal_server_error` | An unexpected error occurred. |

docs/guides/sidebar.ts

@@ -9,6 +9,13 @@ const sidebar: SidebarsConfig = {
       description: "The basic concepts you need to get started.",
       items: [{ type: "autogenerated", dirName: "guides/get-started" }],
     },
+    {
+      type: "category",
+      label: "Fundamentals",
+      collapsed: false,
+      description: "Core technical details about how the Anytype API works.",
+      items: [{ type: "autogenerated", dirName: "guides/fundamentals" }],
+    },
   ],
 };
 

docusaurus.config.ts

@@ -3,6 +3,7 @@
 
 import type * as Preset from "@docusaurus/preset-classic";
 import type { Config } from "@docusaurus/types";
+import { themes as prismThemes } from "prism-react-renderer";
 import { getOpenApiPluginConfig } from "./openapi.config";
 import { openApiConfig } from "./openapi.config";
 
@@ -276,7 +277,16 @@ const config: Config = {
     </div>`,
     },
     prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.vsDark,
       additionalLanguages: ["ruby", "csharp", "php", "java", "powershell", "json", "bash", "dart", "objectivec", "r"],
+      magicComments: [
+        {
+          className: "theme-code-block-highlighted-line",
+          line: "highlight-next-line",
+          block: { start: "highlight-start", end: "highlight-end" },
+        },
+      ],
     },
     languageTabs: [
       {

src/css/custom.css

@@ -200,3 +200,51 @@ h4 {
     transparent 100%
   );
 }
+
+/* Tables */
+table {
+  display: table;
+  width: 100%;
+  border-collapse: separate;
+  border-spacing: 0;
+  border: 1px solid var(--ifm-color-emphasis-200);
+  border-radius: var(--radius-md);
+  margin: var(--spacing-xl) 0;
+  font-size: var(--font-size-small);
+  overflow: hidden;
+}
+
+table th,
+table td {
+  border: none;
+  padding: var(--spacing-sm) var(--spacing-md);
+}
+
+table thead th {
+  background: transparent;
+  border-bottom: 1px solid var(--ifm-color-emphasis-200);
+  font-weight: 600;
+  text-align: left;
+}
+
+table tbody td {
+  border-bottom: 1px solid var(--ifm-color-emphasis-200);
+  vertical-align: top;
+}
+
+table tbody tr:last-child td {
+  border-bottom: none;
+}
+
+table code {
+  font-size: var(--font-size-caption);
+}
+
+[data-theme="dark"] table {
+  border-color: var(--ifm-color-emphasis-300);
+}
+
+[data-theme="dark"] table thead th,
+[data-theme="dark"] table tbody td {
+  border-color: var(--ifm-color-emphasis-300);
+}