HTTP Error Response Examples (System Errors)

The API returns specific JSON bodies for common system errors to aid in debugging. These are distinct from business logic declines (FAILED status).

JSON Structure:

{
  "code": "ERROR_CODE",
  "message": "Human readable message",
  "detailed": "Additional context (optional)"
}

HTTP Code	Error Code	Description	Recommended Action
401	UNAUTHORIZED	Invalid API Key or Signature mismatch.	Verify your X-TW-Signature, secret_key, and api_key.
401	UNAUTHORIZED	Timestamp differs too much from now.	Verify your server time synchronization (X-TW-Timestamp).
403	FORBIDDEN	IP address not allowed.	Check IP allowlist settings in the Merchant Dashboard.
404	NOT_FOUND	Invalid request URI.	Verify the endpoint path (e.g., /v1/payments).
404	NOT_FOUND	Order not found.	The transaction/order ID does not exist or belongs to another merchant.
400	INVALID_REQUEST	Request validation failed.	Check JSON structure and required fields (e.g., amount must be integer).
429	RATE_LIMITED	Too many requests.	Implement backoff logic; retry after 60 seconds.
409	DUPLICATE	Order id was used before.	Use a unique idempotency_key or change the order ID and retry.
500	INTERNAL_ERROR	Temporally system malfunction.	Retry the request; contact support if persistent.

Example Error Responses

401 Unauthorized (Signature Mismatch)

{
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key or Signature mismatch.",
  "detailed": "Please verify your X-TW-Signature and Secret Key."
}

429 Rate Limited

{
  "code": "RATE_LIMITED",
  "message": "Too many requests.",
  "detailed": "Retry after 60 seconds."
}

409 Conflict (Duplicate Order)

{
  "code": "DUPLICATE",
  "message": "Order id was used before",
  "detailed": "Order id was used before. Change order_id and retry"
}

---