ComputeSphere API · Error catalog

Error codes

Every error from the API ships with a stable code and a docs_url pointing here. Look up your error below, or jump straight to the page by appending the code to /errors/.

Response shape

ComputeSphere uses RFC 7807 Problem Details for every error. The Content-Type is application/problem+json. The type field always resolves to a page on this site.

{
  "type":    "https://docs.computesphere.com/errors/rate_limited",
  "title":   "Rate limited",
  "status":  429,
  "code":    "rate_limited",
  "detail":  "Too many requests. Try again after the retry window.",
  "instance": "/v2/projects",
  "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "trace_id":   "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "retry_after_seconds": 60
}

Field	What it carries
type	URL of the docs page for this error code. Resolves to a page on this site.
title	Short human-readable label (2–4 words).
status	The HTTP status. Mirrors the response line.
code	Stable identifier. Switch on this in your client — title and detail may change wording, code will not.
detail	Longer human-readable summary. Safe to surface to end users.
instance	The request path that produced the error.
request_id	UUID v4 generated server-side, or the value of your X-Request-ID request header if you sent one. Always present. Also returned as the X-Request-ID response header. Include in any support ticket.
trace_id	Full W3C traceparent string if your client (or an upstream proxy) sent one. null otherwise — distributed tracing is optional.
retry_after_seconds	Present on 429 and 503 responses when retry is meaningful. Mirrors the Retry-After header.

Field-level validation errors

Validation responses additionally carry an errors[] array — one entry per offending field. Each entry has its own docs_url pointing to the catalog page anchored at that field.

{
  "type":   "https://docs.computesphere.com/errors/validation_failed",
  "code":   "validation_failed",
  "title":  "Validation failed",
  "status": 400,
  "detail": "One or more fields failed validation",
  "instance": "/v2/projects",
  "errors": [
    {
      "field":   "name",
      "code":    "too_short",
      "message": "Service name must be at least 3 characters",
      "docs_url": "https://docs.computesphere.com/errors/validation_failed#too_short"
    }
  ]
}

All error codes

Sign-up & auth

Sign-up throttles, token validity, email verification.

Code	HTTP	Title
SIGNUP_THROTTLE_IP	429	Too many sign-up attempts
SIGNUP_THROTTLE_DEVICE	429	Too many sign-up attempts
EMAIL_ALREADY_REGISTERED	409	Email already registered
INVALID_API_TOKEN	401	API token rejected
API_TOKEN_EXPIRED	401	API token expired
EMAIL_VERIFICATION_REQUIRED	409	Verify your email to continue

Plan, quota & billing

Plan caps, trial state, payment failures.

Code	HTTP	Title
PROJECT_QUOTA_EXCEEDED	402	Project limit reached
SPHERELET_QUOTA_EXCEEDED	402	Compute quota reached
TRIAL_EXPIRED	402	Trial period ended
PAYMENT_REQUIRED	402	Payment failed
PLAN_UPGRADE_REQUIRED	402	Upgrade required

Deployment

Build failures, health checks, image pulls.

Code	HTTP	Title
DEPLOYMENT_FAILED	500	Deployment didn't complete

General

Errors any request can return: validation, sign-in, permissions, conflicts, limits and server errors. The code in type is lower case.

Code	HTTP	Title
invalid_request	400	Invalid request
validation_failed	400	Validation failed
method_not_allowed	405	Method not allowed
payload_too_large	413	Payload too large
unsupported_media_type	415	Unsupported media type
unprocessable_entity	422	Unprocessable entity
precondition_failed	412	Precondition failed
unauthenticated	401	Unauthenticated
forbidden	403	Forbidden
agent_permission_denied	403	Agent permissions don't allow this
approval_self_forbidden	403	Approval needs another admin
not_found	404	Resource not found
gone	410	Resource gone
conflict	409	Conflict
stale_action	409	Proposal is out of date
conversation_in_another_account	409	Conversation is in another account
rate_limited	429	Rate limited
quota_exceeded	429	Quota exceeded
trial_limit_reached	409	Trial limit reached
credit_limit_reached	409	Credit grant limit reached
storage_limit_reached	409	Storage limit reached
credit_cap_reached	409	Credit limit reached
domain_limit_reached	409	Custom domain limit reached
volume_in_use	409	Volume in use
volume_requires_legacy_mounts	422	Volume managed on its service
volume_grow_only	422	Volume can only grow
volume_size_unknown	422	Volume size not offered
restore_point_not_found	404	Restore point not found
size_below_restore_point	422	Size below restore point
restore_points_unavailable	409	No restore points
environment_gone	409	Environment deleted
volume_not_ready	409	Volume not ready
volume_busy	409	Volume being changed
restore_point_too_soon	429	Restore point taken recently
restore_point_limit	409	Restore point limit reached
volume_size_over_plan	422	Volume size above your plan
domain_in_use	409	Domain already in use
wildcard_invalid	400	Wildcard domain not valid
account_locked	409	Account locked
repository_not_found	404	Repository not found
connection_no_access	403	No repository access
connection_revoked	409	Connection revoked
credential_limit_reached	409	Credential limit reached
credential_in_use	409	Credential in use
credential_has_sessions	409	Credential has open sessions
credential_is_default	409	Credential is the default
credential_retired	409	Credential retired
credentials_not_enabled	404	Credentials not available
variable_kind_conflict	409	Variable kind conflict
subscription_exists	409	Subscription exists
stale_quantities	409	Subscription changed
below_running	409	Below what is running
preview_expired	409	Preview expired
ref_not_found	422	Branch or commit not found
path_not_found	422	Folder not found
provider_rate_limited	429	Git provider rate limited
provider_timeout	504	Git provider timed out
invalid_reference	422	Invalid image reference
registry_auth_required	422	Registry credentials required
auth_failed	403	Registry refused the credentials
image_not_found	404	Image not found
reauthentication_required	403	Sign in again
two_step_required	403	Two-step sign-in required
tag_not_found	404	Image tag not found
registry_not_permitted	422	Registry not permitted
unsupported_provider	422	Registry provider not supported
registry_rate_limited	429	Registry rate limited
registry_unreachable	504	Registry unreachable
internal_error	500	Internal error
not_implemented	501	Not implemented
bad_gateway	502	Bad gateway
service_unavailable	503	Service unavailable
tunnel_unavailable	503	Tunnel unavailable
gateway_timeout	504	Gateway timeout