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": "/api/v2/accounts/acc_…/services",
  "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": "/api/v2/services",
  "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

Deployment

Build failures, health checks, image pulls.

Code	HTTP	Title
DEPLOYMENT_FAILED	500	Deployment didn't complete