Errors

RFC 9457 problem documents, the stable error code, pointer semantics, and every code the Spacefast API can return.

Every failure from this API is an RFC 9457 problem document with a stable code. After this page, you can branch on that code, point a user at the exact bad field, and decide whether to retry.

The shape

Failures answer Content-Type: application/problem+json. Nothing else. That covers validation failures, rate limits, IP blocks, and the 404 catch-all alike.

{
  "$schema": "https://api.spacefast.com/schemas/error.json",
  "type": "https://spacefast.com/docs/errors/validation_error",
  "title": "Validation error",
  "status": 422,
  "detail": "files.37.path must be a relative POSIX path.",
  "code": "validation_error",
  "pointer": "/files/37/path",
  "requestId": "01J8ZQ7WYX3M4N5P6R7S8T9V0W"
}

The object is closed. No other members appear.

Branch on code, not on status or detail

code is a typed union in the source, so the server cannot emit one outside the table below. detail is prose and may be reworded. status groups many codes together, and title and type are both mechanical functions of code, so they add nothing a branch can use.

pointer

On a validation failure, pointer is an RFC 6901 JSON Pointer into your request body. Segments are escaped the RFC 6901 way, so ~ becomes ~0 and / becomes ~1.

{ "code": "validation_error", "status": 422, "pointer": "/files/37/path" }

That says the 38th entry of files has a bad path. When a required property is missing, its name is the last segment of the pointer.

A Zod-level validation failure is 422 validation_error. A request body that is not parseable JSON at all is 400 validation_error.

HTTP statuses

The API uses this set, and no others:

recovery and retryable

Every code carries two classifications in the shipped contract. They are not response fields. The sf CLI reads them to tell a caller what to do, and the tables on this page publish the same values so your own client can do the same.

retryable is yes only for retry and wait. Anything else will fail again with the same bytes.

Two retry rules that come from the wire rather than the table. A 429 carries Retry-After in seconds, so honour that number instead of guessing. A 409 idempotency_conflict_in_progress answering your own Idempotency-Key means the first attempt is still running, so keep asking until it resolves.

The codes you will meet first

Request and routing

Credentials and access

Publishing and versions

Builds

Domains

Limits, quotas, and retries

Platform