Troubleshooting
The errors this module produces and what to do about each: INSUFFICIENT_FUNDS, the first-registration block, API Access opt-in, pricing surprises, transfers and webhook rejections.
Where to look first
Configuration → System Logs → Module Log
Every API call is logged there, with the API key and secret redacted. When an action fails, Porkbun’s own error message is passed straight through to the WHMCS admin, which is usually enough on its own.
Porkbun errors carry a machine-readable code, a remediation hint and a request ID. A failure reads:
Insufficient funds. Top up account credit at porkbun.com.
[INSUFFICIENT_FUNDS · request 01a0b60f-0e75-7d18-af2d-8f1e16a82979]Quote that request ID if you contact Porkbun support.
Registration and renewal
“Account must have placed a previous domain registration”
Porkbun blocks the very first registration on an account from the API. Register one domain manually in the Porkbun dashboard, once. Everything after that can be automated.
INSUFFICIENT_FUNDS
The account runs on prepaid credit. Top it up, and turn on auto top-up so it does not happen again mid-renewal-run. Porkbun also offers low-balance alerts.
“Domain is not opted in to API Access”
Porkbun has a per-domain API Access toggle, and renewals, DNS writes and nameserver changes are refused without it.
Domains registered or transferred through the API are opted in automatically, so this only affects domains that were already in the account. Enable it in the Porkbun dashboard.
The daily sync writes a note to the module log when it finds a domain in this state, so check there after your first sync.
The account is not verified
Email and phone must both be verified on the Porkbun account before billable operations will run.
A premium domain order fails
The Porkbun API cannot register, renew or transfer premium domains. The module refuses them up front on registration and transfer, before the customer is charged. Handle premium names in the Porkbun dashboard and invoice manually.
A customer ordered three years and got one
Expected. The API registers the registry-minimum term, usually one year, per call, and a note is written to the module log.
Set Registration terms to 1 year only in the pricing settings and run the sync, which switches years 2–10 off in WHMCS so the longer terms cannot be sold.
“Could not determine the registration price from Porkbun”
The price lookup failed. Usually a transient API problem or a rate limit — check the module log for the underlying call. Also seen on a malformed domain name.
Pricing
The save is refused with a markup rule error
The message names the line number and the problem:
Markup rules, line 3: "sell" is not an operation. Use register, renew or transfer.Fix that line and save again. Syntax is in Markup rules.
“USD is not a configured WHMCS currency”
Porkbun quotes in USD. Either add USD under Configuration → System Settings → Currencies, or set Pricing currency to your own currency and fill in USD conversion rate manually.
The nightly sync is not running
Three things to check, in order:
- Is “Sync retail pricing daily” ticked? It is off by default.
- Have you clicked Save Changes on the registrar since uploading the module? WHMCS only scans a module directory for
hooks.phpwhen the module is activated or saved. Without that, the hook is never registered. - Is the WHMCS daily cron running? Check Utilities → System → System Health or the automation log.
The sync says “assigned to the enom registrar in WHMCS”
Working as intended. The sync never takes a TLD away from another registrar. If you want to move it to Porkbun, change the Auto Registration setting for that TLD in Domain Pricing first.
Prices are not what I expected
Run php pricing.php and read the cost and retail columns side by side. The most common causes:
- A per-TLD rule is matching and replacing the global settings entirely, rather than adding to them.
- The rounding mode is lifting prices to the next
.95or.99. - The minimum margin is lifting a cheap TLD well above the percentage.
- The currency conversion rate is not what you assumed. The preview header states the rate in use.
My multi-year prices disappeared
Registration terms was set to 1 year only, which is the default. It switches years 2–10 off for the TLDs in scope.
Set it to leave other terms as they are, re-enter your multi-year prices in Domain Pricing, and future syncs will only touch year 1.
Transfers
A .uk transfer will not start
.uk inbound transfers cannot be initiated through the Porkbun API. Do those in the Porkbun dashboard. Registration and management of .uk work normally.
“An EPP / authorization code is required”
Porkbun requires one for inbound transfers. Get it from the losing registrar.
A customer wants to transfer away and needs their EPP code
Porkbun has no API for retrieving auth codes. Fetch it from the dashboard: Domain Management → the domain → Get Authorization Code. It is regenerated each time you view it.
A transfer sits pending for a long time
Normal. Registry transfer windows are typically five days unless the losing registrar approves it sooner. TransferSync polls on the daily cron; with webhooks configured, completion is picked up within about a minute instead.
Webhooks
Porkbun refuses to register the endpoint
The URL must be https:// on port 443, resolving to a public address. Private, loopback, link-local and CGNAT addresses are rejected — and re-checked before every delivery, not just at registration.
The URL 404s or is blocked
Many WHMCS installs block direct web access to /modules/. Load the URL in a browser: it should answer 405 POST only. If it does not, adjust your web server rules.
Deliveries are rejected
Check the module log for the reason:
| Reason | Fix |
|---|---|
| no signing secret configured | Paste the secret from --register into the registrar config |
| bad signature | The secret in WHMCS does not match the endpoint’s. Re-run --register and re-paste |
| stale timestamp | Deliveries signed more than five minutes ago are rejected. Check the server clock |
The endpoint has been disabled
Porkbun disables an endpoint after 20 consecutive failures. php webhook.php --list shows the status; re-running --register with the same URL re-enables it.
Connectivity
“Could not reach Porkbun”
A cURL-level failure — the request never got an answer. Check outbound HTTPS to api.porkbun.com is not blocked by a firewall, and that DNS resolves from the server. The module log carries the underlying cURL error.
Rate limit errors
Defaults are 10 availability checks per 10 seconds, 200 domains per minute for bulk checks, and one registration attempt per second. All are configurable per API key — contact Porkbun if you need them raised.