Response envelope

Every JSON response from the API ships in the same envelope. Your client should unwrap it once and let the rest of your code work with the inner data.

Shape

Success
Error

interface SuccessEnvelope<T> {
  requestId: string;       // UUIDv7
  success: true;
  data: T;                 // shape varies per endpoint
}

{
  "requestId": "01900b3f-1ad0-7ab1-9d8a-7b2f54e1d14c",
  "success": true,
  "data": {
    "id": "01h0...",
    "email": "alice@example.com"
  }
}

interface ErrorEnvelope {
  requestId: string;
  success: false;
  error: {
    code: number;          // numeric error code
    key: string;           // stable string key (use this for branching)
    message: string;       // human-readable
  };
}

{
  "requestId": "01900b3f-...",
  "success": false,
  "error": {
    "code": 1500,
    "key": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance"
  }
}

The OpenAPI spec describes the inner data shape only — the envelope is always there.

requestId

Always present, on success and error. UUIDv7 format. Log it on every request so support requests can be traced end-to-end.

console.error({ requestId: body.requestId, key: body.error.key }, "API call failed");

Branching on errors

Always branch on error.key, never on error.message. The message is human-readable and may change; the key is stable.

async function fund(subUserId: string, amount: string) {
  try {
    return await api("/merchant/users/" + subUserId + "/fund", {
      method: "POST",
      body: JSON.stringify({ amount }),
    });
  } catch (err) {
    if (err instanceof SkinsharkError) {
      switch (err.key) {
        case "INSUFFICIENT_BALANCE":
          return notifyOps("merchant balance below threshold");
        case "TRANSFER_CURRENCY_MISMATCH":
          throw new BadRequest("sub-user wallet currency differs from merchant");
        case "IDEMPOTENCY_KEY_REQUIRED":
          throw new BadRequest("missing Idempotency-Key header");
      }
    }
    throw err;
  }
}

A reusable client

Define SkinsharkError once and unwrap there. The rest of your code never touches the envelope.

export class SkinsharkError extends Error {
  constructor(
    public requestId: string,
    public code: number,
    public key: string,
    message: string,
  ) {
    super(message);
    this.name = "SkinsharkError";
  }
}

export async function api<T>(
  path: string,
  init: RequestInit = {},
  onBehalfOf?: string,
): Promise<T> {
  const headers = new Headers(init.headers);
  headers.set("api-key", process.env.SKINSHARK_API_KEY!);
  if (init.body) headers.set("content-type", "application/json");
  if (onBehalfOf) headers.set("on-behalf-of", onBehalfOf);

  const res = await fetch("https://api.skinshark.gg" + path, { ...init, headers });
  const body = await res.json();

  if (!body.success) {
    throw new SkinsharkError(body.requestId, body.error.code, body.error.key, body.error.message);
  }
  return body.data as T;
}

HTTP status vs envelope

Both are set on every response:

2xx ↔ success: true
4xx / 5xx ↔ success: false

If you read the body, the envelope is authoritative. If you only have the status code (e.g. logs), 4xx ≠ retry, 5xx = transient. See Error handling for retry strategy.

Get started

Core concepts

Integration

Real-time

Reference

Shape

requestId

Branching on errors

A reusable client

HTTP status vs envelope

​Shape

​requestId

​Branching on errors

​A reusable client

​HTTP status vs envelope

Shape

requestId

Branching on errors

A reusable client

HTTP status vs envelope