Errors & Status Codes

Standardized JSON error envelope, HTTP status definitions, and retry guidelines for Hashpay API endpoints.

Unified JSON error envelope

All Hashpay API errors return a standard JSON envelope containing status_code, message, and data: null:

Error Envelope Example

{
  "status_code": 400,
  "message": "amount is below the minimum order limit of 10000 IDR",
  "data": null
}

Status Code	Category	Description & Recommended Action
`400`	Bad Request	Validation error (e.g. invalid amount, missing fields, or amount below limit). Check request payload.
`401`	Unauthorized	Invalid or missing `api-key` header, expired JWT token, or incorrect signature. Verify credentials in dashboard.
`403`	Forbidden	Action not allowed for your account tier or key permission level.
`404`	Not Found	Target resource, merchant ID, or order number does not exist.
`429`	Too Many Requests	Rate limit exceeded. Implement exponential backoff before retrying.
`500`	Internal Server Error	Transient server issue. Retry with exponential backoff; if persistent, contact Hashpay support.