HTTP Status Codes

The Pagamio VAS API uses standard HTTP status codes to indicate the success or failure of API requests. Understanding these codes helps you handle errors appropriately.

Status Code Categories

2xx - Success

Status	Meaning	Description
200	OK	Request processed successfully
201	Created	Resource successfully created

4xx - Client Errors

Status	Meaning	Common Causes
400	Bad Request	Invalid input or parameters
401	Unauthorized	Invalid or missing Bearer token
403	Forbidden	Bearer token lacks permissions
404	Not Found	Invalid endpoint or resource
409	Conflict	Duplicate transaction
429	Too Many Requests	Rate limit exceeded

5xx - Server Errors

Status	Meaning	Common Causes
500	Internal Server Error	Server-side issue
503	Service Unavailable	Maintenance or overload

Detailed Status Code Descriptions

200 OK

When returned:

• Successful purchase transaction
• Successfully retrieved data (categories, products, transactions)
• Token generated successfully

Example Response:

{
  "success": true,
  "data": {
    "transactionId": "b9871532-3252-4920-b99e-081dc1488494",
    "status": "COMPLETED",
    "responseCode": 0,
    "responseMessage": "Purchase successful",
    "receipt": {
      "amount": 50.0,
      "reference": "b9871532-3252-4920-b99e-081dc1488494",
      "pin": "1234567890", // If applicable
      "serialNumber": "SN123456",
      "expiryDate": "2025-12-31"
    }
  }
}

400 Bad Request

When returned:

• Missing required fields
• Invalid data format
• Invalid product code
• Validation errors

Example Response:

{
    "responseCode": "1300",
    "responseMessage": "Required fields missing."
}

Common Causes:

• Missing productCode, amount, mobileNumber, or channelId
• Invalid phone number format
• Amount outside allowed range

401 Unauthorized

When returned:

• Missing Authorization header
• Invalid Bearer token
• Expired Bearer token

Example Response:

{
    "responseCode": "1105",
    "responseMessage": "User is not allowed to perform this action"
}

How to Fix:

# Check your token is included
curl -X GET $BASE_URL/products/categories \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

# Generate a new token if expired
curl -X POST $BASE_URL/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'

How to Fix:

• Verify account status in the portal
• Confirm merchant account approval
• Contact support for permission issues

404 Not Found

When returned:

• Invalid API endpoint
• Resource doesn't exist
• Wrong HTTP method

Example Response:

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "No static resource api/v1/.",
    "instance": "/api/v1/"
}

Common Causes:

# ❌ Wrong endpoint
GET /api/v1/product/categories

# ✅ Correct endpoint
GET /api/v1/products/categories

How to Fix:

• Use unique transaction references
• Check transaction history before retrying
• Implement idempotency keys

500 Internal Server Error

When returned:

• Unexpected server-side error
• Service malfunction

Example Response:

{
    "type": "about:blank",
    "title": "Internal Server Error",
    "status": 500,
    "detail": "An unexpected error occurred while processing the request.",
    "instance": "/api/v1/lookups/brands/"
}

How to Fix:

• Retry the request after a delay

• Check API status page

• Contact support if persists

• HTTP Status Code: Indicates the type of error (client vs server)

• Error Code: Provides specific details about what went wrong

Best Practices

1. Check Both Codes - Always check both HTTP status and error code
2. Handle 5xx Errors - Implement retry logic for server errors
3. Don't Retry 4xx Errors - Client errors need request modifications
4. Log Status Codes - Track HTTP status codes for monitoring
5. Use Status for Flow Control - Route error handling based on status code

Related Pages

• Error Code Reference - Application error codes
• Troubleshooting Guide - Step-by-step debugging
• Common Issues - Frequently encountered problems

---

Last updated: October 2025