Error Handling

All API errors follow a consistent format and use standard HTTP status codes.

Error Response Format

{
  "success": false,
  "message": "Description of what went wrong"
}

TIP

The data field is only present when there are additional details (e.g., validation errors). It is omitted entirely — not null — for simple errors.

Validation errors include field-level details in data:

{
  "success": false,
  "message": "validation error",
  "data": [
    {
      "field": "InventoryRequest.game",
      "code": "required",
      "message": "game is a required field"
    },
    {
      "field": "InventoryRequest.partner",
      "code": "required",
      "message": "partner is a required field"
    }
  ]
}

HTTP Status Codes

Code	Meaning	When
200	Success	Request completed successfully
400	Bad Request	Invalid JSON body, validation errors
401	Unauthorized	Missing or invalid API key
403	Forbidden	Merchant account disabled or IP not whitelisted
404	Not Found	Resource doesn't exist (e.g., unknown tx_id or merchant_tx_id)
408	Request Timeout	Upstream request timed out
409	Conflict	Resource already exists (e.g., duplicate merchant_tx_id)
500	Internal Server Error	Something went wrong on our side
502	Bad Gateway	Upstream service error

Common Errors

Missing API Key

Status: 401

{
  "success": false,
  "message": "missing authorization header"
}

Fix: Include X-Api-Key header in your request.

Invalid API Key

Status: 401

{
  "success": false,
  "message": "invalid API key"
}

Fix: Check that your API key is correct and active.

Merchant Disabled

Status: 403

{
  "success": false,
  "message": "merchant account is disabled"
}

Fix: Contact support to reactivate your merchant account.

IP Not Whitelisted

Status: 403

{
  "success": false,
  "message": "invalid IP: 203.0.113.42"
}

Fix: Add your server's IP address to the merchant whitelist.

Invalid Request Body

Status: 400

{
  "success": false,
  "message": "invalid request body"
}

Fix: Ensure the request body is valid JSON.

Validation Error

Status: 400

{
  "success": false,
  "message": "validation error",
  "data": [
    {
      "field": "InventoryRequest.token",
      "code": "len",
      "message": "token must be exactly 8 characters long"
    }
  ]
}

Fix: Check each field error and correct the input.

Not Found

Status: 404

{
  "success": false,
  "message": "not found error"
}

Fix: Verify the id, merchant_tx_id, or tx_id is correct.

Timeout

Status: 408

{
  "success": false,
  "message": "timeout error"
}

Fix: Upstream service was slow. Retry after a few seconds.

Already Exists

Status: 409

{
  "success": false,
  "message": "already exist error"
}

Fix: The merchant_tx_id has already been used. Use a unique transaction ID.

Best Practices

1. Always check success — Don't assume a 200 response means success
2. Handle 502 gracefully — Upstream outages are temporary
3. Parse validation errors — The data array tells you exactly which fields failed
4. Log error responses — Include the full response body for debugging
5. Implement retries — For 408/500/502 errors, retry with exponential backoff