Learn
Reference
Examples
Learn
Reference
Examples

Error Handling

TerrantulaError

Every SDK method throws TerrantulaError on a non-2xx response. It carries the HTTP status and the parsed response body.

import { createClient, TerrantulaError } from '@terrantula/sdk'

const client = createClient('https://terrantula.example.com', 'terr_xxxxxxxxxxxx')

try {
  const entities = await client.entities.list({
    orgId: 'my-org',
    projectId: 'infra',
    envName: 'production',
  })
} catch (err) {
  if (err instanceof TerrantulaError) {
    console.error(`API error ${err.status}:`, err.message)
    // err.body contains the raw parsed response (object or unknown)
    console.error('body:', err.body)
  } else {
    throw err
  }
}

Properties

PropertyTypeDescription
statusnumberHTTP status code (e.g. 401, 404, 422).
bodyunknownParsed JSON response body. Inspect for body.error for the error string.
messagestringHuman-readable message. Extracted from body.error when present; falls back to "Request failed with status N".

withSchema

withSchema attaches a Zod schema to a function. This is used internally by the CLI's command auto-discovery. In most cases you won't need it directly unless you're building tooling on top of the SDK.

import { withSchema } from '@terrantula/sdk'
import { z } from 'zod'

const myFn = withSchema(
  z.object({ orgId: z.string(), name: z.string() }),
  async ({ orgId, name }) => {
    return `Created ${name} in ${orgId}`
  },
)

// myFn.schema is the Zod schema — usable for validation and CLI help text
const result = await myFn({ orgId: 'my-org', name: 'infra' })

SchemaFn type

SchemaFn<S, R> is ((params: z.infer<S>) => Promise<R>) & { readonly schema: S }. It preserves the call signature while adding .schema for introspection.

ON THIS PAGE