Getting started · API errors

API errors

Every error from the ComputeSphere API ships with a stable code, a human-readable message, and a direct link to its catalog entry. Same envelope shape across every endpoint.

The envelope

ComputeSphere uses RFC 7807 Problem Details for every error. The Content-Type header 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/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. Open in a browser, or fetch as Markdown for an AI agent.
`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.

Correlating with our logs

If you want our support team to find your request in the logs, include the request_id in your ticket. It's stable per request and matches the X-Request-ID response header.

If your client already speaks W3C trace context, send a traceparent header on your request — we'll echo the trace id back in the error response and our logs will be correlated to your trace.

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/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"
    }
  ]
}

HTTP status families

The status code tells you what to retry; the code field tells you why.

Status	Family	Retry?
`400`	Bad request — your input is malformed or missing a required field	After fixing the request
`401`	Unauthorized — token missing, expired, or revoked	After getting a fresh token
`402`	Payment required — plan limit, trial expired, or invoice unpaid	After resolving billing
`403`	Forbidden — token is valid but the action isn't allowed	Don't — check the permission
`404`	Not found — the resource doesn't exist (or you can't see it)	Don't
`409`	Conflict — preconditions like email verification not met	After the precondition
`429`	Too many requests — rate limit hit	After `retry_after_seconds`
`500`	Internal error — something went wrong on our side	After a short pause
`502` / `503` / `504`	Upstream / capacity issues	After `retry_after_seconds`

Look up a specific error

The full catalog of application-emitted errors lives at /errors. Each entry has:

What it means — plain-English explanation of the underlying condition
How to fix it — action-led steps for the developer or operator
Retry behavior — whether retry will help and on what cadence
Code samples — how to detect and handle the error in TypeScript, Python, Go, and curl

You can jump straight to any error page by appending the code: https://docs.computesphere.com/errors/<CODE>.

When you're stuck

Every error page is also available as raw markdown — paste the URL into Claude, Cursor, or ChatGPT and they'll have full context for debugging. The Copy as Markdown action in the page header sends the source straight to the clipboard.

If the error includes a trace_id, mention it in support — it lets us locate the exact request in our logs.

API errors

The envelope​

Correlating with our logs​

Field-level validation errors​

HTTP status families​