Error codes

What each Plexivo API error code means, its HTTP status, and what to do about it.

When a request fails, the Plexivo API answers with an HTTP status and a stable code your program can act on. This page lists the codes you are most likely to meet.

Error format#

json

{
  "error": {
    "code": "validation_failed",
    "message": "one or more fields are invalid",
    "details": { "fields": { "storage_gb": ["can only grow (now 20 GB)"] } }
  }
}

code is stable. Build your logic on it.
message explains the problem to a person and may change.
details carries what you need to fix it, such as the fields that failed, when there is something to say.

Idempotency errors use the application/problem+json format, with code, detail and fix. Every response carries an x-trace-id header; quote it when you contact support.

Code	Status	What to do
`unauthorized`	401	The token or API key is missing, wrong, revoked or expired. Check the `Authorization` header, or create a new key.
`reauthentication_required`	401	A console session ended. `details.reason` is `idle` or `absolute`. Sign in again.
`forbidden`	403	Your role, or the key’s permissions, do not allow this. The message says what was refused; for an API key it names the scope needed.
`step_up_required`	403	Confirm your password or authenticator code, then retry.
`support_access_required`	403	Someone outside the organisation tried to reveal a secret or data without an approved request. See Support and agency access.
`organisation_suspended`	403	The organisation cannot create anything new. Contact support.

Requests#

Code	Status	What to do
`validation_failed`	422	Fix the fields listed in `details.fields` and send again.
`not_found`	404	The resource does not exist, or you cannot see it.
`name_taken`	409	Choose another name.
`illegal_transition`	409	The resource is not in a state that allows this. Check its status and retry later.
`quote_expired`, `quote_changed`, `quote_invalid`	409	Ask for a new estimate and confirm the new price.
`price_changed`	409	The price moved since you saw it. Review it and confirm again.
`idempotency_key_reused`	409	Use a new `Idempotency-Key` for a different request.
`idempotency_in_flight`	409	The first request with this key is still running. Wait and retry with the same key.
`invalid_idempotency_key`	400	Use a key of 256 bytes or fewer.
`endpoint_retired`	410	This endpoint is no longer available. The message says what replaced it.

Limits and capacity#

Code	Status	What to do
`rate_limited`	429	Too many requests. Wait for the `Retry-After` seconds and retry.
`too_many_requests`	429	An API key’s per-minute, concurrent or daily limit was reached. See Limits on every key.
`quota_exceeded`	403	Your plan’s limit for this kind of resource is reached. Delete something, or change your plan.
`spend_limit_exceeded`	422	The API key’s monthly spend limit would be passed. Raise the limit or use another key.
`contact_sales`	422	What you asked for is arranged with sales. Talk to sales.
`no_capacity`, `queued_capacity`	503	There is no room for this in its region right now. Nothing was created or charged. Retry in a few minutes.

Billing#

Code	Status	What to do
`plan_required`	402	Choose a plan in Settings → Plan.
`wallet_empty`	402	Add money to your wallet.
`insufficient_funds`	422	The wallet balance is too low for this. Add money.
`first_deploy_verification_required`	428	Complete the one-time check the console asks for before your first deployment.
`not_eligible`	422	The offer, such as migration credits, does not apply. `details.reasons` says why.

Plexivo AI#

Code	Status	What to do
`ai_disabled`	403	Plexivo AI is turned off for this organisation.
`ai_daily_cap`	429	Today’s Plexivo AI limit is reached. Try again tomorrow.
`plan_expired`, `plan_stale`	409	The plan you are approving is out of date. Ask Plexivo AI to plan again.
`ai_unavailable`	503	Plexivo AI is briefly unavailable. Retry shortly.

Temporary problems#

A 503, such as database_unavailable or payment_provider_unavailable, means something Plexivo depends on is briefly unavailable. Retry with backoff and the same Idempotency-Key. A 500 with internal_server_error is ours to fix: send us the x-trace-id.

Updated 27 October 2026