Error Code Data & Component System

A zero-duplication approach for error codes across all API pages. Non-React engineers only touch JSON files; the React component renders everything automatically.

---

File Structure

src/
├── components/
│   └── ErrorCodePage/
│       └── index.js            ← Reusable React component (edit rarely)
└── data/
    └── error-codes/
        ├── customer-object.json      ← Common: Customer object errors
        ├── payment-object.json       ← Common: Payment object errors
        ├── agent-object.json         ← Common: Agent object errors
        ├── consent-object.json       ← Common: Consent object errors
        ├── payment-details-object.json ← Common: Payment Details errors
        └── payment-api.json          ← API-specific: Payment API errors

---

How It Works

1. Common object JSON files — define errors that apply across many APIs (customer, agent, consent, etc.).
2. API-specific JSON files — define errors unique to one API (e.g., payment-api.json).
3. .mdx page — imports the JSON data + component and renders everything.

---

For Non-React Engineers: Adding / Editing Error Codes

Add a new error to an existing category

Open the relevant JSON file (e.g., src/data/error-codes/payment-api.json) and add a new entry to the errors array inside the correct category:

{
  "id": "my-new-error",
  "title": "PAYMENT_METHOD_ERROR",
  "httpStatus": "422 UNPROCESSABLE_ENTITY",
  "message": "Human-readable error message shown to developers",
  "description": "Short explanation of what this error means.",
  "scenario": [
    "When does this error occur?"
  ],
  "resolution": "What should the developer do?",
  "endpoints": ["/v2/payments"],
  "scopes": ["merchant"],
  "sampleResponse": {
    "title": "PAYMENT_METHOD_ERROR",
    "status": 422,
    "detail": "Same message as above"
  }
}

Add a new category

Add a new object to the categories array:

{
  "name": "My New Category",
  "errors": [ /* error objects here */ ]
}

Add a new common object file

1. Create src/data/error-codes/my-object.json following the schema of existing files.
2. Import it in the .mdx page and pass it in commonObjects.

---

For React Engineers: The Component

The <ErrorCodePage> component accepts:

Prop	Type	Description
data	JSON object	API-specific error data with categories[]
commonObjects	Array of JSON objects	(Optional) Common object files to cross-reference
showCommonObjects	boolean	(Optional) Show the common object reference tip box

---

Creating a New API Error Page

1. Create src/data/error-codes/<api-name>.json with your categories and errors.
2. Create a new .mdx file in the docs folder:

---
sidebar_position: 1
slug: /developers/convenient-checkout-api/<api-name>-error-codes
---

import ErrorCodePage from '@site/src/components/ErrorCodePage';
import data from '@site/src/data/error-codes/<api-name>.json';
import customerObject from '@site/src/data/error-codes/customer-object.json';

# My API Error Codes

Description of the API error codes.

<ErrorCodePage
  data={data}
  showCommonObjects={true}
  commonObjects={[customerObject]}
/>

That's it. The summary tables, detail sections, and formatting are all handled automatically.

---

JSON Schema Reference

Common Object File

{
  "objectName": "Customer Object",
  "description": "Short description",
  "referencePath": "/docs/path/to/full-page/",
  "errors": [ /* array of error objects */ ]
}

API-Specific File

{
  "apiName": "Payment API",
  "apiVersion": "v2",
  "basePath": "/v2/payments",
  "commonObjects": ["customer-object", "consent-object"],
  "categories": [
    {
      "name": "Category Name",
      "errors": [ /* array of error objects */ ]
    }
  ]
}

Error Object

{
  "id": "kebab-case-anchor-id",
  "title": "ERROR_TITLE",
  "httpStatus": "422 UNPROCESSABLE_ENTITY",
  "message": "Error message text",
  "description": "Short explanation of the error",
  "scenario": ["When this error occurs"],
  "resolution": "How to fix it",
  "endpoints": ["/v2/payments"],
  "scopes": ["merchant", "user"],
  "sampleResponse": { }
}