Build on ZevCloud
Build on ZevCloud with connected apps
How partner apps, such as AI builders and developer tools, create, deploy and watch services in a person's ZevCloud team with their consent.
A connected app is a partner app that acts in a person’s ZevCloud account with their consent. An AI builder can create a service from the code it wrote, set its environment variables, deploy it and read its logs. The person stays in control. They pick which teams the app may touch, and they can disconnect it at any time.
This page covers using ZevCloud once your app is connected. Getting approved, connecting a person, PKCE, tokens, refresh, webhooks and testing are covered in ZevAuth’s guide, Delegated access to Zev products.
How it works
- Your app is approved for ZevCloud through ZevAuth. See Getting approved.
- Your app sends the person to connect. ZevID signs them in, shows the permissions you ask for and lets them pick teams. See The flow.
- ZevAuth gives your app a 10 minute access token and a refresh token. See Using the access token and Refresh tokens.
- Your app calls the ZevCloud API with that token and a team id.
Quick start: from connected to deployed
Once the person has connected, getting their code live is four calls, plus one check before you create. You don’t need a plan id (the free plan is the default), you don’t look up environments, and the person doesn’t have to connect GitHub to ZevCloud.
- Check limits before creating.
GET /teams/current/limits(withx-team-id) tells you whether the team has free services left, and how many projects and unpaid services your app holds there. IffreeServices.remainingis0, a free create will be refused, so show the person their options first. See Common questions. - Create a project, once per team.
POST /projectswith{ "name": "..." }. It comes with a Production environment. Saveidandenvironments[0].idfrom the response, because your app can’t list projects later. Reuse this project for that team’s next services. - Create the service in that environment:
POST /environments/<environmentId>/services/application. Pick a source from Choosing a source.planIdis optional: leave it out for the free plan, or pass a paid plan and the service waits for the person to pay (see Money). - Set environment variables if the app needs them (
POST /services/<serviceId>/env/bulk). - Deploy (
POST /services/<serviceId>/deployments) and follow the deployment until it reportsrunning.
The end-to-end example shows each request and response.
Common questions
- What is
planId, and where do I get one? It’s optional. Leave it out and the service uses the free plan. To offer a paid plan, take itsidfromGET /public/pricing/deployment-plans?market=<code>(no token needed; it also lists names, limits and prices), using the team’smarket.codefromGET /teams/current/limits. A paid create returns apaymentblock with a link for the person to pay, and the service deploys once they do. See Money. - What is
environmentId? The id of an environment inside a project, not a name like “production” or “staging”. A project your app creates has one environment, Production, and its id isenvironments[0].idin thePOST /projectsresponse. - Do I have to create a project first? Yes, once. Every service lives in a project. Create one the first time you deploy for a team, store its ids, and reuse it.
- What if the person has used all their free services? Each team has a limited number of free services, shared by every service type. Check first with
GET /teams/current/limits: whenfreeServices.remainingis0, a free create returns402 free_limit_reachedwithlimit,used,market,plansUrl,databasePlansUrl,manageServicesUrlanddashboardBillingUrl. Show the person their two options. They can choose a paid plan: take a planidfromplansUrl(already filtered to the team’s market), create withplanId, and show them the payment link from the response (see Money). Or they can delete a free service they no longer need atmanageServicesUrl, then you try the create again. - Does the person have to connect GitHub to ZevCloud? No, unless you choose to build from their GitHub with
sourceMode: "github". Uploads and public URLs need no GitHub connection on ZevCloud.
Choosing a source
| Source | sourceMode | Needs from the person | Use it when |
|---|---|---|---|
| Upload | upload | Nothing | Your app already has the code (you generated it, or you read it from GitHub yourself). You send a tarball; ZevCloud builds it. Set frameworkPreset to one of nextjs, astro, nuxt, remix, sveltekit, vite, node, python, fastapi, django, flask, go, php or ruby. |
| Public URL | public-url | Nothing | The code is in a public Git repository. Any language. |
| GitHub | github | ZevCloud’s GitHub App installed on the repository, and the zevcloud.repos.read scope | You want ZevCloud to build a private repository directly. See Building from GitHub. |
If your app already has access to the person’s GitHub, upload is the smoothest path: fetch the repository archive with your own access, then send it to ZevCloud. The person connects GitHub once, to your app, and nowhere else. Upload flow: create the service with sourceMode: "upload", POST /services/<serviceId>/uploads/url to get an upload URL, PUT the tarball to it, POST /services/<serviceId>/uploads/<uploadId>/complete, then deploy with { "sourceUploadId": "<uploadId>" } in the body of POST /services/<serviceId>/deployments.
Uploading a backend
Uploads build web frontends and backends alike. Pick the frameworkPreset that matches the code:
| Preset | Default port | Installs with | Starts with (when you send no startCommand) |
|---|---|---|---|
fastapi | 8000 | uv.lock, poetry.lock, requirements.txt or pyproject.toml, in that order | uvicorn main:app, or app.main:app when the app is in app/main.py |
flask | 8000 | Same as FastAPI | gunicorn app:app |
django | 8000 | Same as FastAPI, then collectstatic when the settings allow it | gunicorn <project>.wsgi, with the project found from manage.py |
python | 8000 | Same as FastAPI | Nothing. Send a startCommand, or the create is refused with a 400. |
go | 8080 | go mod download | The main package, built as a static binary |
php | 80 | composer install without dev packages | A PHP web server for public/, or the top folder when there is no public/ |
ruby | 3000 | bundle install without the development and test groups | bin/rails server for Rails, otherwise rackup with config.ru |
The server packages the default start commands need (uvicorn, gunicorn) are added when your project doesn’t list them. The app runs as a non-root user and gets its port in PORT. Any default can be replaced with installCommand, buildCommand or startCommand, and rootDirectory points the build at a folder inside the tarball.
Pick the language version with runtimeVersion. Leave it out for the default:
| Runtime | Versions | Default |
|---|---|---|
Python (python, fastapi, django, flask) | 3.10, 3.11, 3.12, 3.13 | 3.12 |
| Go | 1.23, 1.24, 1.25, 1.26, 1.27 | 1.27 |
| PHP | 8.2, 8.3, 8.4 | 8.3 |
| Ruby | 3.2, 3.3, 3.4 | 3.3 |
Any other version is refused with a 400 that lists the choices. For example, a FastAPI backend:
{
"name": "Recipe API",
"slug": "recipe-api",
"sourceMode": "upload",
"frameworkPreset": "fastapi",
"runtimeVersion": "3.12",
"rootDirectory": "backend"
}Send it to POST /environments/<environmentId>/services/application, then upload and deploy as above. A few things to know:
- Python packages with C code compile during the build when they ship no ready-made wheel. Packages that also need a system library at runtime (for example
psycopg2built from source, which needslibpq) won’t load. Use the binary build instead, such aspsycopg2-binaryorpsycopg[binary]. - Go builds with cgo off, so the binary is static. Packages that need cgo, such as
mattn/go-sqlite3, won’t build; use a pure Go driver likemodernc.org/sqlite. Read the port fromPORT. - PHP includes
pdo_mysql,pdo_pgsql,mysqli,bcmath,intl,zip,gd,exif,pcntlandopcache, on top of the usual built-in extensions. Requests that aren’t for a real file go toindex.php, which is what Laravel and Symfony expect. - Ruby must match the version in your
Gemfile, if it names one. Rails needsSECRET_KEY_BASEset as an environment variable. - Django needs your service’s address in
ALLOWED_HOSTS.
Teams
ZevCloud’s targets are teams.
- The person picks teams on the ZevID consent screen.
- Only teams where they are an owner or admin can be picked.
- If your app asks for
zevcloud.services.delete, only teams the person owns can be picked. Teams where they are only an admin show but cannot be chosen. - If they have no team yet, they can create one from the consent screen. It opens ZevCloud’s create-team page and brings them back to finish connecting.
- On every call, the team must be one the person connected, and they must still be an owner or admin of it. If they lost that role, the call fails with
role_lost.
Scopes
Ask only for the scopes your app needs. The person sees each one on the consent screen. See also Scopes by product.
| Scope | Risk | What it allows |
|---|---|---|
zevcloud.services.read | standard | Read services, deployments, build logs, runtime logs, metrics and environment variable names. Values are always masked. |
zevcloud.services.create | standard | Create projects and services, from public URLs or uploads, on the free plan or any public paid plan or database tier. Paid services wait for the person to pay. |
zevcloud.repos.read | high | Build from GitHub repositories the team’s ZevCloud GitHub App can see, and list them. A build can print the whole repository into logs your app reads. |
zevcloud.deploy | standard | Deploy, roll back, approve or reject deployments, and start, stop and restart services. |
zevcloud.env.write | standard | Set and delete environment variables. ZevCloud never returns values, but your build and runtime logs show whatever your code prints. |
zevcloud.services.delete | high | Delete services the app created, only on teams the person owns. |
zevcloud.services.all | high | Act on every service in the team, not only the ones the app created. |
Routes by scope
All paths are relative to https://api.zevcloud.net/v1.
zevcloud.services.read
GET /environments/:environmentId/servicesGET /environments/:environmentId/services/:serviceIdGET /environments/:environmentId/services/:serviceId/currently-runningGET /services/:serviceIdGET /services/:serviceId/paymentGET /teams/current/limits(also works for people signed in to ZevCloud)GET /services/:serviceId/sync-statusGET /services/:serviceId/metricsGET /services/:serviceId/runtime-logsPOST /services/:serviceId/logs/sessionGET /services/:serviceId/deploymentsGET /services/:serviceId/deployments/:deploymentIdGET /services/:serviceId/deployments/:deploymentId/logsPOST /services/:serviceId/deployments/:deploymentId/logs/sessionGET /services/:serviceId/env(names only, values masked)
zevcloud.services.create
POST /projectscreates a project with its Production environment. The response includesenvironments[0].id.POST /environments/:environmentId/services/applicationPOST /environments/:environmentId/services/wordpressPOST /environments/:environmentId/services/databasePOST /environments/:environmentId/services/uploadPOST /services/:serviceId/uploads/urlPOST /services/:serviceId/uploads/:uploadId/complete
zevcloud.repos.read
GET /github/reposlists the repositories ZevCloud can see for this team.GET /github/repos/:owner/:repo/branchesGET /github/repos/:owner/:repo/accesschecks one repository before you create a service from it. See Building from GitHub.- With this scope,
POST /environments/:environmentId/services/applicationalso acceptssourceMode: "github". Deploying, rolling back or approving a deployment of a service that builds from GitHub needs it too.
zevcloud.deploy
POST /services/:serviceId/deployments. The body may includecommitShato roll back, but only to a commit your app deployed.POST /services/:serviceId/deployments/:deploymentId/approvePOST /services/:serviceId/deployments/:deploymentId/rejectPOST /services/:serviceId/startPOST /services/:serviceId/stopPOST /services/:serviceId/restartPOST /services/:serviceId/deployPOST /services/:serviceId/wp-restart-db
zevcloud.env.write
POST /services/:serviceId/envPOST /services/:serviceId/env/bulkDELETE /services/:serviceId/env/:envVarId
zevcloud.services.delete
DELETE /environments/:environmentId/services/:serviceId. Only on teams the person owns. Withoutzevcloud.services.all, only services your app created.
zevcloud.services.all
This scope has no routes of its own. It widens the other scopes from “services this app created” to every service in the team. Together with zevcloud.services.delete, your app can delete any service in teams the person owns, including ones the person created. Ask for both only if your app really manages the whole team.
High-risk scopes
zevcloud.repos.read, zevcloud.services.delete and zevcloud.services.all are high risk. People see them unticked on the consent screen.
- The person must have signed in recently to grant them.
- They end after a confirmation window (30 days by default).
- After that, calls that need them return
high_risk_confirmation_required. Send the person to confirm again through ZevAuth. See High-risk permissions.
Calling the API
Base URL:
https://api.zevcloud.net/v1Send two headers on every call:
Authorization: Bearer <partner access token>
x-team-id: <team id>- The access token comes from ZevAuth and lasts 10 minutes. Refresh it through ZevAuth before it runs out.
x-team-idnames the team you are acting on. It must be a team the person connected. ZevCloud never takes the team from the token or the request body.
What apps can never do
Some actions belong to the person alone. They are refused for every app, whatever scopes it holds, with not_available_to_partners:
- Paying invoices, plan upgrades and anything else to do with billing
- Zev Credit
- Storage subscription changes
- Buying or transferring domains
- Team settings, members, invites and ownership
- Creating or deleting teams
- API keys
- Terminal access and running commands
- File access and downloads
- WordPress credentials, auto-login and SFTP
- Database public access and database credentials
- ZevBox
- Connecting or disconnecting GitHub, and linking GitHub accounts
- Security settings
- Saved addresses
- Policies
- Verification
Projects can be created but not listed or edited. Cross-team lists (/aggregate/*) are not available.
Building from GitHub
Building from a public URL or an upload needs nothing extra. Building from GitHub needs zevcloud.repos.read, a high-risk scope: your app chooses the build steps, so a build can print the whole repository into logs your app reads. If ZevCloud’s GitHub App is installed with access to all repositories, that can cover a whole organisation. Ask for it only if your app really builds people’s GitHub code.
Your app can only build repositories the team’s ZevCloud GitHub App can already see. Which repositories that is stays the person’s choice on GitHub, so you never get wider access than they gave ZevCloud.
Check a repository first:
curl "$ZC/github/repos/acme/api/access" \
-H "Authorization: Bearer $TOKEN" \
-H "x-team-id: $TEAM"If ZevCloud can see it, you get { "ok": true }. Then create the service with sourceMode: "github" and gitRepoUrl: "https://github.com/acme/api". Private repositories get a read-only deploy key automatically.
If not, you get ok: false with an access value, a url and steps to show the person. Creating the service anyway returns the same details with 409 github_access_required.
access | Meaning | url opens |
|---|---|---|
app_not_installed | The ZevCloud GitHub App is not installed on the account or organisation that owns the repository. The team owner connects GitHub in ZevCloud. On an organisation, an organisation owner approves the install. | ZevCloud team settings, Integrations |
repo_not_visible | The app is installed on the owner, but this repository is not in its “Repository access” list. On an organisation, only an organisation owner can change the list. | The installation’s settings page on GitHub |
Show the steps as they come; they already cover personal accounts and organisations. When the person is done, check again.
If the person later removes access on GitHub, takes back zevcloud.repos.read, or lets its confirmation lapse, new builds from that repository stop, including approving a held deployment. While the confirmation has lapsed, those calls return high_risk_confirmation_required.
Only your own services
Every service your app creates is marked as created by your app.
- Without
zevcloud.services.all, every service route refuses services your app did not create, withnot_created_by_partner. - Lists only include your own services.
- With
zevcloud.services.all, your app can act on every service in the team, within its other scopes.
Store the service ids your app creates. You cannot list projects to find them again.
Secrets and money
Secrets
ZevCloud never hands secrets to your app.
- Environment variable values are never returned. Reads show names only.
- Passwords, keys and connection strings are never returned to apps.
- WordPress, database and file-transfer passwords for a new WordPress site are emailed to the person, never to an address your app chooses.
- Billing details (plans, invoices, billing status) are left out of everything your app reads. The one exception is the
paymentblock for a service waiting to be paid, described under Money.
Variables are still given to the code you build and run. If that code prints a value, it shows in build or runtime logs, which your app can read. Don’t print secrets.
Money
Your app never pays and never sees card details. The person pays ZevCloud directly, through ZevPay or the ZevCloud dashboard.
-
Plans and prices depend on the team’s market. Every team belongs to one market, chosen when the team was created, and is billed in that market’s currency. Which plans are sold, and at what price, can differ between markets. Read
market.codeandmarket.currencyfromGET /teams/current/limitsand fetch plans with?market=<code>, for exampleGET /public/pricing/deployment-plans?market=NG. Use only plans from that list. The team’s market always decides: nothing your app sends changes it, and a plan not sold there is refused with400 plan_not_availableand themarket. Teams in a market that is not open can’t create services from your app (403 market_closed). -
Free by default. Leave out
planIdand the service uses the free plan. Leave outdatabasePlanSlugand a database uses the free tier. -
Paid plans are allowed. Pass a plan
idfromGET /public/pricing/deployment-plans, or a database tier fromGET /public/pricing/database-plans(bydatabasePlanSlugor id). Plans that are retired or kept for a special offer are refused with400 plan_not_available. An unknown database tier is a400. -
The service waits for payment. A paid service is created with
status: "pending_payment". It can’t be deployed until the person pays. You can still upload code to it while it waits. -
The create response carries a
paymentblock when payment is needed:"payment": { "required": true, "status": "pending", "invoiceId": "6f1c...", "planName": "Starter", "amount": 5000, "currency": "NGN", "paymentUrl": "https://...", "payInDashboardUrl": "https://console.zevcloud.net/billing?invoice=6f1c..." }amountis in whole units ofcurrency(naira, dollars), not kobo or cents.currencyis the invoice’s currency, which is the team’s billing currency; don’t assume naira. ShowpaymentUrlto the person, or send them topayInDashboardUrlto pay in ZevCloud. When a ZevPay link can’t be used,paymentUrlis the dashboard link too. The team owner also gets the invoice by email, marked as created by your app. -
Find out when it’s paid. Poll
GET /services/<serviceId>/payment(needszevcloud.services.read). It returns the same block while the payment is pending, then{ "required": false, "status": "paid" }. A service that never needed payment returns{ "required": false, "status": "none" }.GET /services/<serviceId>shows the service leavepending_paymentat the same time. ZevCloud doesn’t send your app an event for this yet. -
After payment ZevCloud deploys the service for you. An upload service deploys the latest upload you completed while it waited. If you didn’t upload anything, it stays stopped and ready: upload and deploy as usual.
-
Deploying before payment returns
402 payment_requiredwith the samepaymentblock. -
A few unpaid services at a time. Your app can hold 3 services waiting for payment in each team (unless ZevCloud changes it). Past that, a paid create returns
409 unpaid_limit_reachedwith thelimit. A slot frees up when the person pays, or when you or the person delete one of those services (your app needszevcloud.services.delete). Deleting a service that was never paid cancels its invoice, so nothing is owed. -
Unpaid services don’t wait forever. By default, after 7 days unpaid the team owner gets one email reminding them to pay, with the payment link and the date the service will be removed. After 14 days unpaid the service is removed, its invoice is cancelled and the owner is told. ZevCloud may change these defaults. A service that received any payment is never removed this way.
-
Uploaded code expires after 7 days. Code you upload while a service waits for payment is kept for 7 days. If the person pays later than that, upload and deploy again. A static site created with
POST /environments/<environmentId>/services/uploadkeeps its ZIP while it waits and is published once paid. If the ZIP expired first, the site shows a placeholder page andGET /services/<serviceId>/paymentreturns"reuploadRequired": truewith amessage. -
Test versions of your app create free services only. A paid
planIdor database tier from an app in test mode returns400 paid_plans_live_only, because a paid plan raises a real invoice. See Testing. -
Limits at a glance.
GET /teams/current/limitsreturns what the team can still create:{ "market": { "code": "NG", "currency": "NGN" }, "freeServices": { "used": 3, "limit": 3, "remaining": 0 }, "partnerProjects": { "used": 1, "limit": 10 }, "partnerUnpaidServices": { "used": 0, "limit": 3 }, "upgrade": { "plansUrl": "https://api.zevcloud.net/v1/public/pricing/deployment-plans?market=NG", "databasePlansUrl": "https://api.zevcloud.net/v1/public/pricing/database-plans?market=NG", "dashboardBillingUrl": "https://console.zevcloud.net/billing", "manageServicesUrl": "https://console.zevcloud.net/projects?view=services" } }freeServices.limitandremainingarenullwhen the team has no free limit. A free create is refused exactly whenremainingis0.partnerProjectsandpartnerUnpaidServicesare your app’s own counts in this team, and arenullfor people.marketis the team’s market and billing currency, and the plan links are already filtered to it. -
Your app can create a limited number of projects in each team (10 unless ZevCloud changes it). Past that,
POST /projectsreturns403 project_limit_reachedwith thelimit. Reuse your projects.
Fair use
The person must have accepted ZevCloud’s fair use policy in the console. Until they do, calls return 403 fair_use_required. Send them to the ZevCloud console to accept it, then retry.
End-to-end example
This example creates a project, adds an application from a public Git repository, sets environment variables, deploys it and follows the deployment.
export ZC=https://api.zevcloud.net/v1
export TOKEN=<partner access token>
export TEAM=<team id>1. Create a project
Needs zevcloud.services.create.
curl -X POST "$ZC/projects" \
-H "Authorization: Bearer $TOKEN" \
-H "x-team-id: $TEAM" \
-H "Content-Type: application/json" \
-d '{"name": "Recipe Finder"}'The project comes with a Production environment. Keep environments[0].id from the response.
2. Create an application
Needs zevcloud.services.create. Use sourceMode: "public-url" to build from a public Git repository with no access setup.
curl -X POST "$ZC/environments/<environmentId>/services/application" \
-H "Authorization: Bearer $TOKEN" \
-H "x-team-id: $TEAM" \
-H "Content-Type: application/json" \
-d '{
"name": "Recipe Finder",
"slug": "recipe-finder",
"sourceMode": "public-url",
"gitRepoUrl": "https://github.com/example/recipe-finder",
"gitBranch": "main",
"port": 3000
}'The slug becomes the service’s default address, <slug>.zevcloud.app. Other optional fields include rootDirectory, installCommand, buildCommand, startCommand, isStatic, isSpa, outputDirectory, runtime and runtimeVersion. Keep the service id from the response.
3. Set environment variables
Needs zevcloud.env.write.
curl -X POST "$ZC/services/<serviceId>/env/bulk" \
-H "Authorization: Bearer $TOKEN" \
-H "x-team-id: $TEAM" \
-H "Content-Type: application/json" \
-d '{
"items": [
{"key": "NODE_ENV", "value": "production"},
{"key": "RECIPES_API_KEY", "value": "rk_123", "isSecret": true}
]
}'The response lists the result for each item. Values are never sent back.
4. Deploy
Needs zevcloud.deploy.
curl -X POST "$ZC/services/<serviceId>/deployments" \
-H "Authorization: Bearer $TOKEN" \
-H "x-team-id: $TEAM"Keep the deployment id from the response.
5. Follow the deployment
Needs zevcloud.services.read. Poll the deployment every few seconds until it reaches a final status: running, failed, cancelled or rolled_back.
queued,buildinganddeployingmean keep polling.pending_approvalmeans the team approves deployments before they go out. Keep polling, or approve it withzevcloud.deployif the person asked you to.blockedmeans the team has an unpaid invoice. Stop and tell the person to check ZevCloud.
curl "$ZC/services/<serviceId>/deployments/<deploymentId>" \
-H "Authorization: Bearer $TOKEN" \
-H "x-team-id: $TEAM"Read the build logs:
curl "$ZC/services/<serviceId>/deployments/<deploymentId>/logs" \
-H "Authorization: Bearer $TOKEN" \
-H "x-team-id: $TEAM"See Deployment statuses for every status.
Errors
Errors are JSON:
{
"statusCode": 403,
"code": "not_created_by_partner",
"reason": "not_created_by_partner",
"message": "This app can only act on services it created."
}Branch on reason. The message is for people and may change.
| Reason | Status | What to do |
|---|---|---|
invalid_token | 401 | The token is not valid. Get a new one through ZevAuth. |
stale_token | 401 | The connection changed. Refresh the access token through ZevAuth and retry once. |
grant_not_found | 401 | The person disconnected your app. Ask them to connect again. |
grant_not_found | 503 | ZevCloud could not confirm the connection with ZevID just now. Retry after a few seconds. |
grant_revoked | 401 | The person disconnected your app. Ask them to connect again. |
grant_suspended | 403 | The connection is suspended. Do not retry. Contact ZevID through ZevAuth. |
grant_expired | 401 | A test connection ended. ZevAuth reports the same ending as test_grant_expired. Connect again. |
not_available_to_partners | 403 | This action is for the person only. Send them to ZevCloud. |
scope_not_granted | 403 | Your app does not hold the scope. Ask the person to connect again with it. |
scope_paused | 403 | The permission is paused, for this connection or for your app everywhere (level: "approval"). Do not retry. See Paused permissions. |
high_risk_confirmation_required | 403 | Send the person to confirm the high-risk permission again through ZevAuth. |
team_required | 400 | Add the x-team-id header. |
team_not_in_grant | 403 | The person did not connect this team. Ask them to add it. |
team_suspended | 403 | The team is suspended. Do not retry. The person can see why in ZevCloud. |
role_lost | 403 | The person is no longer an owner or admin of this team. |
owner_required | 403 | Deleting needs the person to own the team. |
not_created_by_partner | 403 | Your app did not create this service. |
rollback_not_own_commit | 403 | You can only roll back to a commit your app deployed. |
payment_required | 402 | The service is waiting for payment, so it can’t be deployed yet. Show the person payment.paymentUrl from the response, then poll GET /services/:serviceId/payment. |
plan_not_available | 400 | That plan or database tier can’t be chosen, or isn’t sold in the team’s market (then the response has market). Pick one from GET /public/pricing/deployment-plans?market=<code> or GET /public/pricing/database-plans?market=<code>, or leave it out for the free one. |
market_closed | 403 | The team’s market is not open, so your app can’t create services there. Do not retry. The person can contact ZevCloud. |
free_limit_reached | 402 | The team has used all its free services. The response has limit, used, market, plansUrl, databasePlansUrl, manageServicesUrl and dashboardBillingUrl. Offer the person a paid plan (create again with planId), or send them to manageServicesUrl to delete a free service, then retry. |
paid_plans_live_only | 400 | Your app is in test mode, which creates free services only. Leave out planId (or the database tier), or use the live version of your app. |
unpaid_limit_reached | 409 | Your app already has limit services waiting for payment in this team. Wait for the person to pay, or delete one. |
project_limit_reached | 403 | Your app has created as many projects as it can in this team. Reuse one. |
github_access_required | 409 | ZevCloud can’t see the repository. Show the person the url and steps from the response. |
fair_use_required | 403 | Send the person to the ZevCloud console to accept the fair use policy. |
rate_limited | 429 | Wait for the Retry-After header or retryAfterSeconds, then retry. |
ZevAuth’s Errors page covers errors from connecting, tokens and refresh.
Rate limits
Limits apply per app:
- 120 requests a minute
- 10 deploys a minute
Over the limit, calls return 429 rate_limited with a Retry-After header and retryAfterSeconds in the body. See also ZevAuth’s Rate limits.
Attribution
Everything your app does is recorded with your app and the person it acts for.
- People see “Deployed by <your app>” on deployments your app starts.
- Team owners and admins see connected apps in their team settings.
- People manage and disconnect apps on the ZevID account site.
When a person disconnects, your calls start failing with grant_revoked. ZevAuth can also tell you through webhooks. See Revocation.
Testing
Test versions of your app use ZevAuth test environments.
- A test version connects only to the ZevCloud teams of people on your own team.
- Calls work the same as for a live app, except that a test version can only create free services. A paid plan or database tier returns
400 paid_plans_live_only. - Test connections end on their own. After that, calls fail with
grant_expired(ZevAuth calls ittest_grant_expired) and you connect again.
See Test environments.
Updated at, Monday, October 26, 2026