docs: improve docs config, error codes, and navigation

docs.json

@@ -86,14 +86,6 @@
               "api-reference/fx-account/accounts/list-accounts",
               "api-reference/fx-account/accounts/get-account",
               "api-reference/fx-account/accounts/submit-account-for-review",
-              "api-reference/fx-account/documents/upload-account-document",
-              {
-                "group": "Funding instructions",
-                "icon": "money-bill-transfer",
-                "pages": [
-                  "api-reference/fx-account/funding-instructions/list-funding-instructions"
-                ]
-              },
               {
                 "group": "UBOs",
                 "icon": "users",
@@ -102,12 +94,26 @@
                   "api-reference/fx-account/beneficial-owners/list-ubos",
                   "api-reference/fx-account/beneficial-owners/get-ubo",
                   "api-reference/fx-account/beneficial-owners/update-ubo",
-                  "api-reference/fx-account/beneficial-owners/remove-ubo",
-                  "api-reference/fx-account/documents/upload-ubo-document"
+                  "api-reference/fx-account/beneficial-owners/remove-ubo"
                 ]
               }
             ]
           },
+          {
+            "group": "Documents",
+            "icon": "file-arrow-up",
+            "pages": [
+              "api-reference/fx-account/documents/upload-account-document",
+              "api-reference/fx-account/documents/upload-ubo-document"
+            ]
+          },
+          {
+            "group": "Funding instructions",
+            "icon": "money-bill-transfer",
+            "pages": [
+              "api-reference/fx-account/funding-instructions/list-funding-instructions"
+            ]
+          },
           {
             "group": "Operations",
             "icon": "arrows-rotate",
@@ -188,6 +194,10 @@
   "metadata": {
     "lastUpdatedDate": true
   },
+  "contextual": {
+    "options": ["copy", "view", "claude", "chatgpt", "grok", "cursor", "mcp"],
+    "display": "header"
+  },
   "footer": {
     "socials": {
       "github": "https://github.com/tracefinance",

guides/principles/errors.mdx

@@ -48,9 +48,22 @@ All errors follow the same shape:
 | Code | HTTP status | Description |
 | --- | --- | --- |
 | `INVALID_DATA` | 400 | Request body failed validation |
-| `RESOURCE_NOT_FOUND` | 404 | The requested resource does not exist |
-| `IDEMPOTENT_ID_CONFLICT` | 409 | Idempotency key was already used |
-| `INVALID_STATUS_CHANGE` | 422 | The resource cannot transition to the requested state |
+| `REQUIRED` | 400 | Required field is missing or blank |
+| `INVALID_UUID` | 400 | Field value is not a valid UUID |
+| `INVALID_ENUM` | 400 | Field value is not a valid enum option |
+| `INVALID_DATE` | 400 | Field value is not a valid date format |
+| `INVALID_TYPE` | 400 | Field value does not match the expected type |
+| `MISSING_REQUIRED_HEADER` | 400 | Required HTTP header is missing |
+| `INCOMPATIBLE_CURRENCY` | 400 | Currency does not match the expected value |
+| `INVALID_FILTER_FORMAT` | 400 | Filter query parameter is malformed |
+| `RESOURCE_NOT_FOUND` | 404 | Requested resource does not exist |
+| `IDEMPOTENT_ID_CONFLICT` | 409 | Idempotency key was already used with a different request |
+| `RESOURCE_ALREADY_EXISTS` | 409 | Resource with the given identifier already exists |
+| `ATTRIBUTE_MISMATCH` | 409 | Field value conflicts with existing data |
+| `INVALID_MFA_CODE` | 409 | Provided MFA code is incorrect |
+| `INVALID_STATUS_CHANGE` | 422 | Resource cannot transition to the requested state |
+| `CANNOT_EXECUTE_ACTION` | 422 | Action is not allowed in the current resource state |
+| `REQUIRED_ATTRIBUTE_IS_NULL` | 422 | Required attribute is missing or null |
 | `MFA_NOT_ENABLED` | 422 | Multi-factor authentication is required but not configured |
 
 ### Retry guidance

guides/principles/pagination.mdx

@@ -17,7 +17,6 @@ List endpoints return paginated responses using cursor-based pagination. This ap
 | `cursor` | string | — | Cursor returned from a previous response |
 | `direction` | string | — | Pagination direction: `NEXT` or `PREVIOUS` |
 | `sortOrder` | string | `DESCENDING` | Sort direction: `ASCENDING` or `DESCENDING` |
-| `includeTotalMatches` | boolean | `false` | Whether to include the total matching count in the response |
 
 ### Response structure
 
@@ -32,8 +31,7 @@ Every list response includes a `meta` object alongside the `data` array:
   "meta": {
     "previousCursor": null,
     "nextCursor": "eyJpZCI6ImFjY18wMDIifQ",
-    "total": 45,
-    "totalMatches": 45
+    "total": 45
   }
 }
 ```
@@ -43,7 +41,6 @@ Every list response includes a `meta` object alongside the `data` array:
 | `previousCursor` | Cursor to fetch the previous page. `null` on the first page. |
 | `nextCursor` | Cursor to fetch the next page. `null` on the last page. |
 | `total` | Number of items returned in the current page. |
-| `totalMatches` | Total items matching the current filters. Only present when `includeTotalMatches=true`. |
 
 ## Examples
 

quickstart.mdx

@@ -36,8 +36,7 @@ import SandboxNote from '/snippets/sandbox-note.mdx';
       "meta": {
         "previousCursor": null,
         "nextCursor": null,
-        "total": 0,
-        "totalMatches": 0
+        "total": 0
       }
     }
     ```

snippets/pagination-response.mdx

@@ -6,8 +6,7 @@ List endpoints return a paginated response:
   "meta": {
     "previousCursor": "string or null",
     "nextCursor": "string or null",
-    "total": 42,
-    "totalMatches": 42
+    "total": 42
   }
 }
 ```