Errors and request IDs

Every error uses one envelope, and errors is always an array, so one code path handles every failure:

{
  "errors": [
    {
      "type": "request",
      "code": "input_missing",
      "field": "/name",
      "message": "name is required.",
      "retryable": false,
      "suggested_action": "Supply the required value at field, then retry.",
      "docs_url": "https://typeship.dev/docs/typeship-api/errors#input_missing"
    }
  ],
  "request_id": "req_k3j2h8f0a1b2c3d4"
}

Handling errors

Branch on type and code, and honor retryable. Use message only for logs and display.

const body = await response.json();
for (const error of body.errors ?? []) {
  if (error.type === "rate_limit" || error.code === "idempotency_key_in_use") {
    await sleep(Number(response.headers.get("Retry-After") ?? 1) * 1000);
    return retry(); // same request, same Idempotency-Key
  }
  if (error.type === "auth") return reauthenticate(error.code); // auth_required, api_key_invalid, token_invalid
  if (error.type === "organization") return askToUpgrade(error.message); // quota_exceeded, feature_not_available
  if (error.retryable) return retryOnceWithBackoff();
  return fix(error.field, error.suggested_action); // change the request before retrying
}

• Read every entry. A 400 lists up to 50 independent problems so you can fix them in one pass. field is a JSON Pointer into the part named by in; header pointers use lowercase names, such as /idempotency-key.
• Do not retry plan limits. A capped generation still succeeds and reports omitted operations in coverage. For coverage.reason: "anonymous", offer signup_url; for "free_plan", offer upgrade_url.
• Wait the stated time. Retry-After gives the seconds to wait on a 429. Responses carry RateLimit-Limit and RateLimit-Remaining, so you can pace before the limit.

The Typeship SDKs raise typed errors carrying this envelope, the Typeship CLI wraps it in its own JSON envelope, and the Typeship MCP server returns it as the tool error.

Error types

Request errors

Type request.

Input

State

Versions and releases

Publishing

Drafts

Go SDK dependencies

Authentication errors

Type auth.

Idempotency errors

Type idempotency.

Rate limit errors

Type rate_limit.

Organization errors

Type organization.

Source errors

Type source.

API errors

Type api.

Errors on resources

Generations, Publications, and Drafts carry an errors array in the same entry shape. On a Generation or Publication each entry also has a required phase:

{
  "id": "gen_7h2p5d9c3m8w1k6q",
  "object": "generation",
  "status": "completed",
  "errors": [
    {
      "type": "source",
      "code": "repository_disconnected",
      "phase": "delivery",
      "message": "Reconnect the GitHub repository parcel-example/parcel-client.",
      "retryable": false,
      "suggested_action": "Reconnect the Target's GitHub repository, then retry the operation.",
      "docs_url": "https://typeship.dev/docs/typeship-api/errors#repository_disconnected"
    }
  ]
}

A completed Generation can carry delivery errors; its files remain available. An empty errors array means no recorded failure. On a recorded failure, retryable describes that failure's cause: true means a new generation or publishing attempt can succeed unchanged, which you start with the operation in suggested_action. Getting the resource does not retry it, and replaying the original Idempotency-Key returns the cached response, so use a new key. When every Target in a Project generation fails, the request itself returns an error envelope with each failure's target_id.

A Draft's errors lists what blocks it while its status is action_required, one entry per finding, such as each failed required check.

Request IDs

Every response carries a server-generated Request-Id header, and every JSON body repeats it as request_id. Responses without a JSON body, such as package downloads, HEAD responses, and redirects, carry it only in the header. Typeship ignores a caller-supplied Request-Id. Include the ID when you report a problem:

curl -sS https://typeship.dev/api/v1/organization \
  -H "Authorization: Bearer $TYPESHIP_TOKEN" -o response.json
jq -r '.request_id' response.json