📚 API Error Code Documentation Guidelines

This document provides a standardized template and best practices for documenting API error codes in the Convenient Checkout project. Consistent error documentation helps developers, integrators, and support teams quickly identify, troubleshoot, and resolve issues.

---

🎯 Why Document Error Codes?

Benefit	Description
🔍 Clarity	Clear error documentation reduces confusion and support requests
🛠️ Debugging	Developers can quickly identify the root cause of issues
📐 Consistency	Ensures all APIs follow the same error reporting standards
👥 User Experience	Helps integrators and clients handle errors gracefully

---

Payment API Error Codes

Error Code Summary

Error Codes

Error Title	HTTP Status Code	Error Category	Error Message
UNAUTHORIZED	401	API Gateway Error	UnAuthorized
FORBIDDEN	403	API Gateway Error	insufficient scope
INVALID_REQUEST	400	CCG Schema Validation Error	merchantTransactionId is required
INVALID_REQUEST	400	CCG Schema Validation Error	vendorPaymentMethodId is required
PAYMENT_METHOD_ERROR	406	CCG Business Validation Error	payment method not found
PAYMENT_METHOD_ERROR	406	Payment Processor Validation	one of the payments failed due to insufficient funds
PAYMENT_ERROR	403	CCG Business Validation Error	Payment failed after maximum retries.

Error Code Details

insufficient scope

insufficient scope

Scenario: The request was made with valid authentication, but the client does not have the required permissions (scope) to access the requested resource.

• API Endpoint: Any protected endpoint
• Applicable Scope: Any insufficient or missing scope

Sample Request

{
  "action": "access_protected_resource"
  // token does not have required scope
}

Sample Response

{
  "title": "FORBIDDEN",
  "detail": "insufficient scope",
  "status": 403
}

UnAuthorized

UnAuthorized

Scenario: API Gateway rejected the request due to invalid or missing client credentials.

Sample Request

Authorization: Bearer <invalid-or-missing-token>

Sample Response

{
  "title": "UnAuthorized",
  "detail": "UnAuthorized",
  "status": 401
}

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
• Applicable session modes: PAYMENT, PAYMENT_WITH_WALLET

Sample Request

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

Sample Response

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

Vendor Payment Method ID Required

vendorPaymentMethodId is required

Scenario: The vendorPaymentMethodId field is missing in the request payload.

• API Endpoint: v2/payments, v2/token/payments
• Applicable Scope: merchant-pci, user
• Applicable session modes: PAYMENT, PAYMENT_WITH_WALLET

Sample Request

{
  "merchantTransactionId": "12345",
  "amount": 100.00
  // missing vendorPaymentMethodId
}

Sample Response

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

Payment Method Not Found

payment method not found

Scenario: The provided payment method does not exist, is misspelled, or is not supported by the system.

Sample Request

{
  "merchantTransactionId": "12345",
  "amount": 100.00,
  "paymentMethod": "invalid-method"
}

Sample Response

{
  "title": "PAYMENT_METHOD_ERROR",
  "detail": "payment method not found",
  "status": 406
}

Maximum Retries Reached

Maximum number of retries reached.

Scenario: This error occurs when the system has attempted to process the payment multiple times and has reached the maximum allowed retry limit.

Sample Request

{
  "transactionId": "failed-multiple-times-123"
}

Sample Response

{
  "title": "PAYMENT_ERROR",
  "status": 403,
  "detail": "Payment failed after maximum retries."
}

Payment Failed - Insufficient Funds

one of the payments failed due to insufficient funds

Scenario: One of the payment attempts failed because the account did not have enough funds to complete the transaction.

Sample Request

{
  "merchantTransactionId": "12345",
  "amount": 100.00,
  "paymentMethod": "credit-card"
}
// The card has insufficient funds

Sample Response - Single Allocation

{
  "title": "PAYMENT_METHOD_ERROR",
  "detail": "one of the payments failed due to insufficient funds",
  "status": 406,
  "paymentAllocations":[
    {
        // allocation details
        "error":{
            "title": "PAYMENT_METHOD_ERROR",
            "detail": "payment failed due to insuff fund",
            "errorDetails":{
                // venfdor details
            }
        }
    }

  ]
}

Sample Response - More than one allocation

{
  "title": "PAYMENT_METHOD_ERROR",
  "detail": "one of the payments failed due to insufficient funds",
  "status": 406,
  "paymentAllocations":[
    {
        // allocation details
        "error":{
            "title": "PAYMENT_METHOD_ERROR",
            "detail": "one of the payments failed due to insufficient funds",
            "errorDetails":{
                "code":"",
                "message":""
            }
        }
    },
    {
        // allocation details
        "error":{
            "title": "PAYMENT_METHOD_ERROR",
            "detail": "payment failed due to declined card",
            "errorDetails":{
                // venfdor details
            }
        }
    }

  ]
}

---

Best Practices for Error Code Documentation

📋 Required Documentation Elements

For each error code, provide the following information:

• 📋 Scenario: When and why this error occurs
• 📤 Sample Request: Example of a request that triggers the error
• 📥 Sample Response: Example of the error response (use title and detail fields)
• 🌐 API Endpoints: Which endpoints can return this error
• 🎯 Scope: Required permissions or applicable scopes

---