# Troubleshooting

## 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](/developers/deploy-and-rollback). |
| 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.