Common API error codes

The Billplz API returns standard HTTP status codes to indicate whether a request succeeded or failed. This article lists every error code the API can return, explains what triggers each one, and describes how to resolve it.

All error responses return JSON. For rate limit errors, the response includes an error object with type and message fields. For other errors, the response body varies by endpoint.

Error code reference

401 — Unauthorized

Your Billplz Secret Key is incorrect or missing.

Common causes:

• The Secret Key is mistyped, truncated, or contains extra whitespace.
• You're using a sandbox key against the production endpoint, or vice versa. Sandbox keys only work with billplz-sandbox.com; production keys only work with billplz.com.
• The Basic Auth credential is not formatted correctly. When using cURL, pass the key as the username with a trailing colon (:) and no password.

How to fix:

1. Go to your Billplz dashboard and copy the Billplz Secret Key from Settings > Keys & Integration.
2. Confirm you're using the correct key for the correct environment (sandbox or production).
3. Test authentication by calling the webhook rank endpoint:

curl https://www.billplz.com/api/v4/webhook_rank \
  -u {your_secret_key}:

A successful response returns a JSON object with a rank value. If you still see Unauthorized, reset your Secret Key from the dashboard. See [Get your Billplz Secret key]().

404 — Not found

The resource you requested does not exist.

Common causes:

• The Bill ID, Collection ID, or other resource ID in the URL is incorrect.
• The endpoint URL is misspelled or uses the wrong API version (e.g., /v3/ instead of /v4/).

How to fix:

1. Verify the resource ID matches the value returned when the resource was created.
2. Confirm you're using the correct endpoint URL and API version. Refer to the Billplz API documentation for valid endpoints.

422 — Unprocessable entity

Your request is well-formed but contains invalid parameters or references a resource that cannot be processed.

Common causes:

• A required parameter is missing or empty. For example, creating a bill requires collection_id, email or mobile, name, amount, callback_url, and description.
• A parameter value is in the wrong format. The amount field must be a positive integer in the smallest currency unit (cents) — pass 500 for MYR 5.00, not 5.00.
• The mobile number is missing the country code or contains spaces/dashes. Use the format +60122345678 or 60122345678.
• You're trying to delete a bill that has already been paid.
• You're creating a Payment Order but your Payment Order Limit is insufficient. The API returns the message You do not have enough payments.
• You're trying to deactivate an already-inactive collection or activate an already-active collection. [Verify: API docs confirm the error message but do not specify the HTTP status code — confirm this returns 422]

How to fix:

1. Check the endpoint's required arguments in the Billplz API documentation and confirm every required field is present and correctly formatted.
2. For Payment Order limit errors, reload your Payment Order Limit before retrying. See Reload your Payment Order limit.
3. For collection activation errors, check the collection's current status before calling the activate or deactivate endpoint.

429 — Too many requests

You've exceeded the API rate limit.

How rate limiting works:

• Rate limiting applies to GET endpoints only.
• The default limit is 100 requests per 5-minute window. Accounts flagged for excessive usage may be reduced to 10 requests per 5-minute window without prior notice.
• The limit is cumulative across all GET endpoints per IP address or account — a request to one endpoint reduces the remaining quota for all other GET endpoints within the same window.

Response headers:

Every GET response includes rate limit headers:

{
  "error": {
    "type": "RateLimit",
    "message": ["Too many requests"]
  }
}

How to fix:

1. Check the RateLimit-Reset header and wait for the window to reset before retrying.
2. Reduce polling frequency. Do not repeatedly call the Get a Bill endpoint to check payment status — use callbacks instead. Abusing the Get a Bill endpoint can result in your IP address being blocked.
3. Cache responses where possible to avoid unnecessary repeat requests.
4. If you need higher limits, review your integration to reduce GET calls, or contact [team@billplz.com].

500 — Internal server error

Something went wrong on Billplz's servers.

How to fix:

1. Wait a few minutes and retry the request.
2. If the error persists, check the Billplz status page or contact team@billplz.com with the endpoint, request body (excluding your Secret Key), and the time of the error.

503 — Service unavailable

Billplz is temporarily offline for maintenance.

How to fix:

1. Wait and retry after a few minutes.
2. Check the Billplz status page for maintenance updates.