Version: v2

API Error Code Document Guidelines

This guide provides comprehensive instructions for documenting API error codes in the Convenient Checkout project. Error documentation consists of two parts: MDX pages (user-facing documentation) and JSON data files (structured error data consumed by React components).

When to Use This Guide

Use this guide when:

Creating error code documentation for a new API (e.g., Payment API, Refund API, Session API)
Adding new error codes to existing API documentation
Creating reusable error objects (customer, payment, payment method objects)
Documenting allocation-level errors for multi-allocation operations (split tender)

🚀 Quick Start

Most Common Tasks

I want to...

✅ Add a new error to an existing API ← Most common
- Update JSON file → Error renders automatically
📘 Create error docs for a new API ← Complete walkthrough
- Create JSON file → Create MDX file → Done
🔧 Create a reusable error object ← For common objects
- Create common JSON → Register in API → Import in MDX
🎯 Document split tender allocation errors ← For multi-allocation APIs
- Add allocationErrors array → Render in MDX

Quick Links:

📋 JSON Field Reference — What each field means
📊 Error Categories Reference — Which category to use
✅ Validation Checklist — Pre-commit checks
🔧 Troubleshooting — Fix common issues

✅ Adding a New Error Code

Time: ~5 minutes | Difficulty: Easy

This is the most common task — adding a single error to an existing API's error documentation.

Step 1: Identify the Category

Choose the appropriate category for your error:

Category	Use When
Authorization error	OAuth token issues, scope problems, merchant linking errors
Resource Not Found error	Invalid IDs, non-existent resources, cross-merchant access
Schema validation error	Missing fields, invalid JSON, type mismatches, max length violations
Business Rule Violation Error	Domain logic failures (refund > payment, duplicate ID, insufficient balance)
Payment Processor Error	Processor-level failures

Decision tree: Authorization → Resource Not Found → Schema → Business Rule → Processor

Step 2: Add to JSON File

Open the API's JSON file: docs/03-developers/5-convenient-checkout-api/4-error-codes/{api-name}-api.json

Find the appropriate category and add your error:

📝 JSON Template - Click to expand

{
  "name": "Schema validation error",
  "errors": [
    {
      "id": "payment-amount-required",
      "title": "INVALID_REQUEST",
      "httpStatus": "400",
      "message": "amount is required",
      "scenario": [
        "When amount field is missing in the payment request"
      ],
      "resolution": "Include the amount field with a positive integer value.",
      "scopeWithEndPoint": [
        {
          "merchant": [
            "POST /v2/payments"
          ]
        }
      ],
      "sampleResponse": {
        "title": "INVALID_REQUEST",
        "status": 400,
        "detail": "amount is required"
      },
      "description": "Error returned when amount is missing."
    }
  ]
}

Step 3: Verify

✅ That's it! The error automatically renders in the MDX page if:

Category name matches exactly (case-sensitive)
JSON is valid
All required fields are present

Preview: Run yarn start and navigate to the error code page.

📄 Creating an MDX Error Code Page

Time: ~10 minutes | Difficulty: Easy

Create a new error code documentation page for an API.

Template

Create file: docs/03-developers/5-convenient-checkout-api/4-error-codes/{api-name}-error-codes.mdx

📄 Complete MDX Template - Click to expand

---
sidebar_position: 2
slug: /developers/convenient-checkout-api/error-codes/{api-name}-error-codes
toc_max_heading_level: 4
---

import {
  CategoryErrorSummary,
  CategoryErrorDetails,
  ToggleAllErrorsButton
} from '@site/src/components/ErrorCodePage';
import data from './{api-name}-api.json';

# {API Name} Error Codes

This page documents all error codes for the {API Name} (v2).

## Error Summary

### Authorization error
<CategoryErrorSummary data={data} category="Authorization error" />

### Resource Not Found error
<CategoryErrorSummary data={data} category="Resource Not Found error" />

### Schema validation error
<CategoryErrorSummary data={data} category="Schema validation error" />

### Business Rule Violation Error
<CategoryErrorSummary data={data} category="Business Rule Violation Error" />

### Payment Processor Error
<CategoryErrorSummary data={data} category="Payment Processor Error" />

## Error Details

<div style={{marginBottom: '1.5rem'}}>
<ToggleAllErrorsButton />
</div>

### Authorization error
<CategoryErrorDetails data={data} category="Authorization error" />

### Resource Not Found error
<CategoryErrorDetails data={data} category="Resource Not Found error" />

### Schema validation error
<CategoryErrorDetails data={data} category="Schema validation error" />

### Business Rule Violation Error
<CategoryErrorDetails data={data} category="Business Rule Violation Error" />

### Payment Processor Error
<CategoryErrorDetails data={data} category="Payment Processor Error" />

Key Points:

Import components from @site/src/components/ErrorCodePage
Import JSON data file
Use <CategoryErrorSummary> for summary tables
Use <CategoryErrorDetails> for expandable details
Include <ToggleAllErrorsButton> in Error Details section

📋 JSON Field Definitions

Required Fields (All Errors Must Have These)

Field	Type	Example	Rules
`id`	string	`"payment-id-not-found"`	Unique, kebab-case
`title`	string	`"NOT_FOUND"`	UPPER_SNAKE_CASE
`httpStatus`	string	`"404"`	String, not number
`message`	string	`"paymentId not found"`	Clear, user-facing
`scenario`	array	`["valid paymentId but non-existent"]`	Bullet points
`resolution`	string	`"Verify the paymentId exists"`	Actionable guidance
`sampleResponse`	object	`{ "title": "NOT_FOUND", "status": 404, ... }`	Matches API response
`description`	string	`"Error returned when paymentId not found"`	One sentence

Optional Fields

Field	Type	When to Use
`scopeWithEndPoint`	array	Show which scope + endpoint combinations return this error

📊 Error Categories

Errors are organized by lifecycle stage:

Category	When to Use	Examples
Authorization error	API Gateway blocks request	OAuth issues, scope problems
Resource Not Found error	Resource doesn't exist	Invalid IDs, cross-merchant access
Schema validation error	Request structure invalid	Missing fields, type mismatches
Business Rule Violation Error	Domain logic fails	Refund > payment, duplicate ID
Payment Processor Error	Processor rejects transaction	Generic processor errors

Decision Tree: Authorization → Resource Not Found → Schema → Business Rule → Processor

🔧 Creating Common Error Objects

Time: ~15 minutes | Difficulty: Medium

Create reusable error objects for fields that appear across multiple APIs (e.g., customer, payment, paymentMethod).

When to Create a Common Object

Create a common object when:

✅ The object appears in multiple API endpoints
✅ Validation rules are consistent across APIs
✅ You want to maintain a single source of truth for object validation errors

Examples:

customer-object.json — Used by Payment API, Refund API, Session API
payment-object.json — Used by Payment API, Refund API
payment-method-object.json — Used by Payment API, Payment Method API

Step 1: Create the JSON File

Location: docs/03-developers/5-convenient-checkout-api/4-error-codes/common/{object-name}-object.json

Example: customer-object.json

📝 Common Object JSON Template - Click to expand

{
  "objectName": "Customer Object",
  "description": "Validation errors for the customer object.",
  "categories": [
    {
      "name": "Schema validation error",
      "errors": [
        {
          "id": "customer-hsid-invalid-format",
          "title": "INVALID_REQUEST",
          "httpStatus": "400",
          "message": "customer.hsid must be a valid UUID format",
          "scenario": [
            "When customer.hsid is not in UUID format"
          ],
          "resolution": "Ensure customer.hsid is a valid UUID (e.g., 123e4567-e89b-12d3-a456-426614174000).",
          "scopeWithEndPoint": [
            {
              "merchant": [
                "POST /v2/payments"
              ]
            }
          ],
          "sampleResponse": {
            "title": "INVALID_REQUEST",
            "status": 400,
            "detail": "customer.hsid must be a valid UUID format"
          },
          "description": "Error returned when customer.hsid format is invalid."
        }
      ]
    }
  ]
}

🔗 Steps 2-5: Register and Use Common Object - Click to expand

Step 2: Register in API JSON

Add the object name to the API's commonObjects array:

{
  "apiName": "Payment API",
  "apiVersion": "v2",
  "basePath": "/v2/payments",
  "commonObjects": [
    "customer-object",
    "payment-object",
    "payment-details-object"
  ],
  ...
}

Step 3: Import in MDX

import customerObject from './common/customer-object.json';

Step 4: Add to Error Summary

#### Customer Object

<ObjectErrorSummary object={customerObject} />

Step 5: Add to Error Details

#### Customer Object

<ObjectErrorDetails object={customerObject} />

🎯 Documenting Allocation Errors

Allocation errors apply to split tender operations where a parent transaction spawns multiple child allocations (e.g., charging two cards). Each allocation can fail independently with processor-specific error codes.

When to Document Allocation Errors

Document allocation errors when:

✅ The API supports multi-allocation operations (split tender)
✅ Errors occur at the allocation level (within paymentAllocations[] or refundAllocations[] arrays)
✅ Processor returns allocation-specific error codes

Allocation Error Structure

Allocation errors are grouped by label (error family) and include multiple processor error code samples:

📝 Allocation Error JSON Template - Click to expand

allocationErrors belongs on the parent error object that represents the multi-allocation failure (typically inside the Payment Processor Error category). It is not a root-level field of the API JSON file.

{
  "categories": [
    {
      "name": "Payment Processor Error",
      "errors": [
        {
          "id": "payment-processor-error",
          "description": "Error returned when all paymentAllocations failed during processing.",
          "allocationErrors": [
            {
              "label": "card_declined",
              "description": "Card was declined without a specific reason. Customer should try a different payment method.",
              "scenario": [
                "This can happen when the payment processor returns:",
                "ach_verification_failure: ACH verification failure",
                "card_declined: Card was declined for an unspecified reason",
                "card_error: Generic card error"
              ],
              "sampleResponse": [
                {
                  "error": {
                    "title": "PAYMENT_ERROR",
                    "detail": "Payment method could not be authorized. Please try a different payment method.",
                    "errorDetails": {
                      "code": "ach_verification_failure",
                      "message": "Payment method could not be authorized. Please try a different payment method."
                    }
                  }
                },
                {
                  "error": {
                    "title": "PAYMENT_ERROR",
                    "detail": "Payment method could not be authorized. Please try a different payment method.",
                    "errorDetails": {
                      "code": "card_declined"
                    }
                  }
                }
              ]
            },
            {
              "label": "insufficient_funds",
              "description": "Card or account has insufficient funds to complete the payment.",
              "scenario": [
                "This can happen when the payment processor returns:",
                "insufficient_funds: Card has insufficient funds"
              ],
              "sampleResponse": [
                {
                  "error": {
                    "title": "PAYMENT_ERROR",
                    "detail": "Your card has insufficient funds.",
                    "errorDetails": {
                      "code": "insufficient_funds",
                      "message": "Your card has insufficient funds.",
                      "declineCode": "insufficient_funds"
                    }
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

How to Group Allocation Errors

Group allocation errors by merchant action or user messaging:

🏷️ Allocation Error Grouping Reference - Click to expand

Group Label	When to Use	Examples
`card_declined`	Generic decline, no specific reason	`card_declined`, `card_error`, `generic_decline`
`insufficient_funds`	Not enough balance	`insufficient_funds`, `balance_insufficient`
`expired_card`	Card is expired	`expired_card`
`invalid_card`	Invalid card number or details	`invalid_number`, `invalid_expiry_year`, `incorrect_cvc`
`blocked_card`	Card is blocked/restricted	`lost_card`, `stolen_card`, `restricted_card`
`issuer_authorization_required`	Issuer declined for security	`do_not_honor`, `pickup_card`, `fraudulent`

Adding Allocation Errors to MDX

### PaymentAllocation processor error

::::tip[HTTP Status Codes]

- Allocation-specific errors are returned under `paymentAllocations[n]`.
- HTTP status is NA (inherited from parent `422 UNPROCESSABLE_ENTITY`).

:::caution[Error Code Coverage]
 - Only known documented combinations are listed; more may occur.
 - `error.errorDetails` reflects vendor data; structure not guaranteed.
:::
::::

<AllocationErrorSummary data={data} />

In the Error Details section:

### Payment Allocation processor error

<AllocationErrorDetails data={data} />

⭐ Best Practices

JSON Data Guidelines

✅ DO:

Use kebab-case for id fields ("payment-id-not-found")
Use UPPER_SNAKE_CASE for title fields ("NOT_FOUND", "INVALID_REQUEST")
Use lowercase for HTTP status codes as strings ("404", "400")
Write user-facing messages that are clear and actionable
Provide multiple scenario bullet points covering all edge cases
Include resolution with specific developer actions
Use scopeWithEndPoint array with scope → endpoint mapping
Keep description concise (one sentence for summary tables)
Always include a sampleResponse object

❌ DON'T:

Mix case styles (e.g., "PaymentIdNotFound")
Use numeric HTTP status codes (404 instead of "404")
Write vague error messages ("An error occurred")
Skip the resolution field
Use the legacy endpoints array (use scopeWithEndPoint instead)
Duplicate errors across common objects and API files
Include internal error codes or stack traces in sample responses

MDX Page Guidelines

✅ DO:

Follow the category order: Authorization → Resource Not Found → Schema Validation → Business Rule → Processor → Allocation
Use consistent heading levels (### for categories, #### for objects)
Import only the common objects you actually use
Include a "Toggle All Errors" button in the Error Details section
Provide introductory text explaining what errors are covered
Use admonitions (:::tip, :::caution) for allocation error context

❌ DON'T:

Import unused common objects
Skip the Error Summary section
Mix the order of categories
Hardcode error details directly in MDX (always use JSON + components)
Create multiple MDX pages for the same API version

Naming Conventions

Item	Convention	Example
MDX file	`{api-name}-error-codes.mdx`	`payment-error-codes.mdx`
JSON file	`{api-name}-api.json`	`payment-api.json`
Common object	`{object-name}-object.json`	`customer-object.json`
Error ID	`{object}-{field}-{issue}` (kebab-case)	`customer-hsid-invalid-format`
Allocation label	`{error_family}` (snake_case)	`insufficient_funds`

Categorization Decision Tree

Start: Does the request reach CCG Platform?
│
├─ NO → "Authorization error" (API Gateway blocks it)
│
└─ YES → Does the resource exist?
   │
   ├─ NO → "Resource Not Found error"
   │
   └─ YES → Is the request structure valid?
      │
      ├─ NO → "Schema validation error"
      │
      └─ YES → Does it pass business rules?
         │
         ├─ NO → "Business Rule Violation Error"
         │
         └─ YES → Processor interaction
            │
            ├─ Parent-level failure → "Payment Processor Error"
            │
            └─ Allocation-level failure → "PaymentAllocation Processor Error"

📘 Complete Example: Adding a New API

Let's walk through documenting errors for a new Refund API.

📝 Complete Refund API Example - Click to expand

Step 1: Create JSON File

File: docs/03-developers/5-convenient-checkout-api/4-error-codes/refund-api.json

{
  "apiName": "Refund API",
  "apiVersion": "v2",
  "basePath": "/v2/refunds",
  "commonObjects": [
    "payment-object"
  ],
  "categories": [
    {
      "name": "Authorization error",
      "errors": [
        {
          "id": "refund-forbidden-merchant",
          "title": "FORBIDDEN",
          "httpStatus": "403",
          "message": "403 FORBIDDEN. RequestId: ${x-request-id}",
          "scenario": [
            "x-merchant-id in header not linked to OAuth token"
          ],
          "resolution": "Ensure x-merchant-id is linked to clientId in OAuth token.",
          "scopeWithEndPoint": [
            {
              "merchant": [
                "POST /v2/refunds",
                "GET /v2/refunds"
              ]
            }
          ],
          "sampleResponse": {
            "title": "FORBIDDEN",
            "status": 403,
            "detail": "403 FORBIDDEN. RequestId: ${x-request-id}"
          },
          "description": "Error when x-merchant-id not linked to OAuth token."
        }
      ]
    },
    {
      "name": "Business Rule Violation Error",
      "errors": [
        {
          "id": "refund-exceeds-payment-amount",
          "title": "REFUND_ERROR",
          "httpStatus": "422",
          "message": "Refund amount cannot exceed original payment amount",
          "scenario": [
            "Refund amount + previous refunds > original payment amount"
          ],
          "resolution": "Ensure total refund amount does not exceed the original payment amount.",
          "scopeWithEndPoint": [
            {
              "merchant": [
                "POST /v2/refunds"
              ]
            }
          ],
          "sampleResponse": {
            "title": "REFUND_ERROR",
            "status": 422,
            "detail": "Refund amount cannot exceed original payment amount"
          },
          "description": "Error when refund exceeds original payment amount."
        }
      ]
    }
  ]
}

Step 2: Create MDX File

File: docs/03-developers/5-convenient-checkout-api/4-error-codes/refund-error-codes.mdx

---
sidebar_position: 3
slug: /developers/convenient-checkout-api/error-codes/refund-error-codes
toc_max_heading_level: 4
---

import {
  CategoryErrorSummary,
  CategoryErrorDetails,
  ToggleAllErrorsButton
} from '@site/src/components/ErrorCodePage';
import data from './refund-api.json';

# Refund API Error Codes

This page documents all error codes for the Refund API (v2). Each error includes the code name, HTTP status, description, recommended developer action, and notes where applicable.

## Error Summary

### Authorization error

<CategoryErrorSummary data={data} category="Authorization error" />

### Business Rule Violation Error

<CategoryErrorSummary data={data} category="Business Rule Violation Error" />

## Error Details

<div style={{marginBottom: '1.5rem'}}>

<ToggleAllErrorsButton />

</div>

### Authorization error

<CategoryErrorDetails data={data} category="Authorization error" />

### Business Rule Violation Error

<CategoryErrorDetails data={data} category="Business Rule Violation Error" />

Step 3: Verify Rendering

Start the development server: yarn start
Navigate to /docs/developers/convenient-checkout-api/error-codes/refund-error-codes
Verify:
- ✅ Error Summary tables render with all errors
- ✅ Error Details render in expandable sections
- ✅ Toggle All Errors button works
- ✅ Sample responses are properly formatted

✅ Validation Checklist

Before committing error code documentation:

📋 Full Validation Checklist - Click to expand

JSON File Validation

MDX File Validation

Content Quality

Error messages are user-friendly and actionable
Scenarios cover all known edge cases
Resolutions are specific and testable
No internal implementation details exposed
Processor error details caveat included for allocation errors
HTTP status code explanations included where needed

Reference Materials

Existing Implementations:

Payment Error Codes

Related Documentation:

Example Error Codes Reference

Below are example error codes showing the old manual documentation format vs. the new component-driven approach. Always use the component-driven approach for new documentation.

❌ Old Approach (Manual HTML) — DO NOT USE

Error Code Summary

Error Title	HTTP Status Code	Error Category	Error Message
UNAUTHORIZED	401	API Gateway Error	UnAuthorized
INVALID_REQUEST	400	CCG Schema Validation Error	merchantTransactionId is required

Error Code Details

Merchant Transaction ID Required

merchantTransactionId is required

Scenario: The merchantTransactionId field is required and missing in the request payload.

API Endpoint: v2/payments, v2/token/payments
Applicable Scope: merchant, merchant-pci, user

Sample Request

{
  "amount": 100.00,
  "paymentMethodId": "uuid"
  // missing merchantTransactionId
}

Sample Response

{
  "title": "INVALID_REQUEST",
  "detail": "merchantTransactionId is required",
  "status": 400
}

Issues with this approach:

❌ Requires manual HTML/Markdown for each error
❌ Inconsistent formatting across documents
❌ Difficult to maintain and update
❌ No single source of truth
❌ Error data embedded in MDX (not reusable)
❌ No automatic summary tables

✅ New Approach (Component-Driven) — ALWAYS USE THIS

JSON Data File: docs/03-developers/5-convenient-checkout-api/4-error-codes/payment-api.json

{
  "apiName": "Payment API",
  "apiVersion": "v2",
  "basePath": "/v2/payments",
  "categories": [
    {
      "name": "Schema validation error",
      "errors": [
        {
          "id": "merchant-transaction-id-required",
          "title": "INVALID_REQUEST",
          "httpStatus": "400",
          "message": "merchantTransactionId is required",
          "scenario": [
            "When merchantTransactionId field is missing in the request"
          ],
          "resolution": "Include merchantTransactionId field in your request payload.",
          "scopeWithEndPoint": [
            {
              "merchant": [
                "POST /v2/payments"
              ]
            }
          ],
          "sampleResponse": {
            "title": "INVALID_REQUEST",
            "status": 400,
            "detail": "merchantTransactionId is required"
          },
          "description": "Error when merchantTransactionId is missing."
        }
      ]
    }
  ]
}

MDX File: docs/.../payment-error-codes.mdx

import { CategoryErrorSummary, CategoryErrorDetails } from '@site/src/components/ErrorCodePage';
import data from './payment-api.json';

## Error Summary

### Schema validation error

<CategoryErrorSummary data={data} category="Schema validation error" />

## Error Details

### Schema validation error

<CategoryErrorDetails data={data} category="Schema validation error" />

Benefits:

✅ Single source of truth (JSON)
✅ Automatic rendering via React components
✅ Consistent formatting across all docs
✅ Easy to add/update errors
✅ Reusable components
✅ Search and filter capabilities
✅ Automatic summary tables

❓ FAQs

💡 Frequently Asked Questions - Click to expand

Q: Can I have errors in multiple categories?

Yes, add separate error objects to different category arrays in the JSON file.

Q: How do I handle the same error across multiple APIs?

Create a common object if validation logic is identical, otherwise duplicate the error in each API's JSON file with API-specific details.

Q: What if I need to update an error message?

Update the JSON file only; the MDX page will automatically reflect the change.

Q: How do I preview changes locally?

Run yarn start and navigate to the error code page. Changes to JSON files hot-reload automatically.

Q: Can I add custom sections to the MDX page?

Yes, but keep the standard structure (Summary → Details). Add custom content between sections with clear headings.

Q: What if an allocation error doesn't fit into an existing label group?

Create a new label group in the allocationErrors array. Choose a descriptive label that reflects the user action or error family.

Q: How do I handle processor-specific error codes that vary by vendor?

Document all known variants in the scenario array. Use sampleResponse array to show multiple examples. Include a caveat that vendor error structure may vary.

Q: Should I document every possible HTTP status code?

Document all application-level errors. Standard HTTP errors (500 Internal Server Error, 503 Service Unavailable) from infrastructure don't need documentation unless there's app-specific context.

🔧 Troubleshooting

Component Not Rendering

Problem: Component shows nothing or displays raw JSON.

Solutions:

Verify the category name in MDX exactly matches the JSON (case-sensitive)
Check that the JSON file is imported correctly
Validate JSON syntax (run linter)
Check browser console for React errors

Error Not Appearing in Summary

Problem: Error in JSON but not in the summary table.

Solutions:

Verify category name matches exactly
Check that description field is present
Ensure error is in the correct category array
Clear build cache: yarn clear && yarn start

Sample Response Not Formatting

Problem: Sample response shows as plain text or doesn't expand.

Solutions:

Verify sampleResponse is an object, not a string
Check JSON syntax (missing quotes, commas)
Ensure all required fields are present in sampleResponse

Allocation Errors Not Showing

Problem: <AllocationErrorSummary> or <AllocationErrorDetails> shows nothing.

Solutions:

Verify allocationErrors array is on the parent error object inside categories[].errors[] (e.g., the split-tender processor error entry) — it is not a root-level field of the API JSON file
Check that label and description fields are present for each allocation error
Ensure sampleResponse is an array (not object)

💡 Reference Implementation: See Payment Error Codes for a complete working example of this guideline in action.

🏛️ Architecture & Technical Details

📐 Technical Architecture & File Structure - Click to expand

Component-Driven Architecture

Error code documentation uses a component-driven architecture for consistency and maintainability:

┌─────────────────────────────────────────────────────────────┐
│  MDX Page (docs/03-developers/.../error-codes/xxx-api.mdx) │
│  • Imports React components for rendering                   │
│  • Imports JSON data files                                   │
│  • Provides structure and narrative                          │
└────────────┬────────────────────────────────────────────────┘
             │ imports
             ↓
┌─────────────────────────────────────────────────────────────┐
│  React Components (src/components/ErrorCodePage)            │
│  • CategoryErrorSummary / CategoryErrorDetails              │
│  • ObjectErrorSummary / ObjectErrorDetails                   │
│  • AllocationErrorSummary / AllocationErrorDetails           │
│  • ToggleAllErrorsButton                                     │
└────────────┬────────────────────────────────────────────────┘
             │ consumes
             ↓
┌─────────────────────────────────────────────────────────────┐
│  JSON Data Files (docs/03-developers/5-convenient-checkout-api/4-error-codes/)                    │
│  • API-specific: payment-api.json, refund-api.json          │
│  • Common objects: customer-object.json, payment-object.json│
└─────────────────────────────────────────────────────────────┘

Benefits:

✅ Single source of truth (JSON)
✅ Automatic rendering via React components
✅ Reusable common objects across APIs
✅ Consistent formatting
✅ Easy to maintain and update

File Structure

Directory Layout:

workspace/
├── docs/
│   └── 03-developers/
│       └── 5-convenient-checkout-api/
│           └── 4-error-codes/
│               ├── payment-error-codes.mdx       ← MDX pages
│               ├── refund-error-codes.mdx
│               └── session-error-codes.mdx
└── src/
    ├── components/
    │   └── ErrorCodePage/                        ← React components
    │       ├── index.tsx
    │       └── ...
    └── data/
        └── error-codes/
            ├── payment-api.json                  ← API-specific JSON
            ├── refund-api.json
            ├── session-api.json
            └── common/                           ← Reusable objects
                ├── customer-object.json
                ├── payment-object.json
                ├── payment-method-object.json
                └── payment-details-object.json

JSON Schema Templates

API-Level JSON File Template:

Location: docs/03-developers/5-convenient-checkout-api/4-error-codes/{api-name}-api.json

{
  "apiName": "Payment API",
  "apiVersion": "v2",
  "basePath": "/v2/payments",
  "commonObjects": ["customer-object", "payment-object"],
  "categories": [
    {
      "name": "Authorization error",
      "errors": [ /* error objects */ ]
    }
  ],
  // Note: allocationErrors is NOT a root-level field.
  // It belongs on the specific error object (inside categories[].errors[])
  // that represents the multi-allocation failure — see Documenting Allocation Errors.
}

Common Object JSON File Template:

Location: docs/03-developers/5-convenient-checkout-api/4-error-codes/common/{object}-object.json

{
  "objectName": "Customer Object",
  "description": "Validation errors for the customer object.",
  "categories": [
    {
      "name": "Schema validation error",
      "errors": [ /* error objects */ ]
    }
  ]
}

🚀 Quick Start​

Most Common Tasks​

✅ Adding a New Error Code​

Step 1: Identify the Category​

Step 2: Add to JSON File​

Step 3: Verify​

📄 Creating an MDX Error Code Page​

Template​

📋 JSON Field Definitions​

Required Fields (All Errors Must Have These)​

Optional Fields​

📊 Error Categories​

🔧 Creating Common Error Objects​

When to Create a Common Object​

Step 1: Create the JSON File​

Step 2: Register in API JSON​

Step 3: Import in MDX​

Step 4: Add to Error Summary​

Step 5: Add to Error Details​

🎯 Documenting Allocation Errors​

When to Document Allocation Errors​

Allocation Error Structure​

How to Group Allocation Errors​

Adding Allocation Errors to MDX​

⭐ Best Practices​

JSON Data Guidelines​

MDX Page Guidelines​

Naming Conventions​

Categorization Decision Tree​

📘 Complete Example: Adding a New API​

Step 1: Create JSON File​

Step 2: Create MDX File​

Step 3: Verify Rendering​

✅ Validation Checklist​

JSON File Validation​

MDX File Validation​

Content Quality​

Reference Materials​

Example Error Codes Reference​

Error Code Summary​

Error Code Details​

Merchant Transaction ID Required​

❓ FAQs​

🔧 Troubleshooting​

Component Not Rendering​

Error Not Appearing in Summary​

Sample Response Not Formatting​

Allocation Errors Not Showing​

🏛️ Architecture & Technical Details​

Component-Driven Architecture​

File Structure​

JSON Schema Templates​

🚀 Quick Start

Most Common Tasks

✅ Adding a New Error Code

Step 1: Identify the Category

Step 2: Add to JSON File

Step 3: Verify

📄 Creating an MDX Error Code Page

Template

📋 JSON Field Definitions

Required Fields (All Errors Must Have These)

Optional Fields

📊 Error Categories

🔧 Creating Common Error Objects

When to Create a Common Object

Step 1: Create the JSON File

Step 2: Register in API JSON

Step 3: Import in MDX

Step 4: Add to Error Summary

Step 5: Add to Error Details

🎯 Documenting Allocation Errors

When to Document Allocation Errors

Allocation Error Structure

How to Group Allocation Errors

Adding Allocation Errors to MDX

⭐ Best Practices

JSON Data Guidelines

MDX Page Guidelines

Naming Conventions

Categorization Decision Tree

📘 Complete Example: Adding a New API

Step 1: Create JSON File

Step 2: Create MDX File

Step 3: Verify Rendering

✅ Validation Checklist

JSON File Validation

MDX File Validation

Content Quality

Reference Materials

Example Error Codes Reference

Error Code Summary

Error Code Details

Merchant Transaction ID Required

❓ FAQs

🔧 Troubleshooting

Component Not Rendering

Error Not Appearing in Summary

Sample Response Not Formatting

Allocation Errors Not Showing

🏛️ Architecture & Technical Details

Component-Driven Architecture

File Structure

JSON Schema Templates