Troubleshooting
Common API errors with their causes and fixes, plan limits, blocked deploys, and provisioning problems.
First step
Call GET /token. It shows the scopes, which of them work right now (usable_scopes), and why others do not (blocked_scopes).
Errors
| Status | Typical message | Cause | Fix |
|---|---|---|---|
401 |
Missing, wrong or expired API token | No Authorization header, a typo, an expired or revoked token. |
Check the header. Make a new token or use New secret. |
401 |
The person who made this token is no longer in the team | The maker left the team. | Make a new token with a current member. |
403 |
This token can't be used from <ip> |
The token has an allowed-address list and your address is not in it. | Call from an allowed address, or edit the token's list. |
403 |
... doesn't have the <scope> scope |
The token was made without it. | Make a new token with that scope. |
403 |
The team's plan doesn't include <scope> |
The plan (or the platform administrator) does not allow it. | Change plan or ask support. |
403 |
The team owner switched <scope> off for API tokens |
The owner's rule under API, then Rules. | Ask the owner. |
403 |
The token's maker no longer has the permission "..." | The person's role or custom permissions changed. | Change the permissions, or make a token from someone who has them. |
403 |
... must turn on two-factor authentication first | The team requires it. | The maker turns on two-factor sign-in. |
404 |
No such server/site | Wrong id, another team, or outside the token's limits. | List with GET /servers or GET /sites. Check the token's limits. |
409 |
Can't be deployed / already running | Site not active, watch-only, no repository yet, a deployment already queued or running, or being moved. | Read the site's status. Wait. Connect a repository. |
409 |
Idempotency-Key request still running | A retry arrived while the first request was running. | Wait and retry. |
422 |
Validation error with errors |
A field is missing or invalid. | Read each field's message. |
422 |
Idempotency-Key already used for a different request | Same key, different body or path. | Use a new key. |
429 |
Too many requests | Over 120 a minute, or 30 changes a minute. | Wait and retry slower. |
"blocked_scopes"
blocked_scopes maps each blocked scope to the reason. The four reasons are: the token does not have it, the plan does not include it, the owner switched it off, or the maker lacks a permission. Only the person who can change that thing can fix it.
Plan limits
422 when you add a server, site, environment or member over your plan's limit. Remove one, or upgrade. Environments and standby copies count as sites.
Deployments
| Problem | What to do |
|---|---|
Deployment failed with code_findings |
The code scan stopped it before anything changed. Do not retry. A person reviews the commit; if it is safe, a team member who manages the site approves it in the dashboard (site, Deployments). See Deploy and roll back. |
Deployment failed, no findings |
Read log in the single-deployment answer. Common: build error, failed health check (pfcloud switched back to the previous release), failed database backup before the deploy. |
Deploy answers 409 |
No repository connected yet (PUT /sites/{site}/github), site not active, or another deployment is running. |
Site stuck in creating |
Check the run log in the dashboard. If it failed, fix the cause and POST /sites/{site}/retry. |
Provisioning and servers
| Problem | What to do |
|---|---|
Server stays pending |
pfcloud's key is not in authorized_keys for root. Use GET /servers/{server}/authorized-key, then POST /servers/{server}/connect. |
Server failed |
Read GET /servers/{server}/runs and the run output. Fix, then connect again. |
| A PHP version is missing on a new Ubuntu release | Newer Ubuntu releases may not yet have packages for every PHP version. pfcloud falls back to a version the server offers; if you need a specific one and the install fails, choose another version (GET /servers/{server}/php shows what is installed) or install it from a source your server supports. |
| Change refused on a server | Many server changes (firewall, databases, PHP, fixes) refuse servers that pfcloud only adopted, so existing sites are never disturbed. |
| Cannot add the server's IP | It is already in the team, or was deleted and is waiting to be purged (30 days). |
Still stuck
Open Help in the dashboard, or use the report-a-problem link shown next to failed runs: it gives support an error code (ERR- plus six characters) to look up.