Errors

import { Aside } from ‘@astrojs/starlight/components’;

The Melbora API returns standard HTTP status codes with a JSON body:

{
  "error": "human-readable message",
  "details": null
}

error is always a string — branch on the HTTP status code plus the message text. details is optional and contains structured context for the more elaborate failures (e.g. the failed validator output on a 400).

4xx — caller error

`400` Bad Request

The request body or query failed validation. Common messages:

Message contains	Cause	Fix
`Body required`	Missing JSON body on POST/PUT	Send a JSON object
`Invalid JSON body`	Body was non-JSON or malformed	Validate JSON before sending
`Invalid request body — <field>: <issue>`	Zod schema validation failed	Read the field/issue pair printed in `error`
`Invalid path params — <field>: <issue>`	URL path param failed validation	Check path against `/v1/<resource>/{id}` shape
`name is required`, `slug is required`, etc.	Missing field on a hand-validated route	Add the field
`slug already exists`	Slug collision (globally unique)	Pick a different slug
`must be #RRGGBB hex`	Non-hex color value	Use `#RRGGBB` format

`401` Unauthorized

Message contains	Fix
`Missing token` / `No Authorization header`	Send `Authorization: Bearer vc_pat_...`
`Invalid token`	Token revoked or copied truncated; mint a fresh one
`Your session is stale`	Re-login (client-only — Cognito subject vanished underneath the JWT)

`403` Forbidden

Message contains	Fix
`Admin role required`	Use an admin token, or hit the client-scoped equivalent endpoint
`Not authorized to ...`	The Website is owned by a different client
`Website does not have the <feature> feature enabled`	`vantage websites features <id> --<feature>` first
`... is not available on the <tier> tier`	Upgrade the SEO/feature tier

`404` Not Found

Message contains	Fix
`Website <id> not found`	Verify with `vantage websites list`
`Client <id> does not exist`	The clientId is wrong / not yet created
`Domain not found`	Check `vantage domains list <id>`
`Pending transfer not found`	The transfer was cancelled or already accepted

`409`-ish (returned as `400` today)

The API folds conflicts into 400 rather than 409:

Message contains	Cause
`Someone else saved while you were editing`	Content SHA mismatch on `PUT /content` — refetch + retry

`429` Too Many Requests

Hand-rolled rate limiting isn’t documented per-endpoint yet. Assume ~10 req/s per token as a safe ceiling for sustained traffic. Back off and retry on any non-2xx that looks transient.

5xx — server error

500 returns include the error message plus optional details. Retry idempotent reads (GET) freely; for non-idempotent writes confirm the side effect first (vantage websites get <id> after a 500 from create).

502 / 503 / 504 usually mean Lambda was cold, throttled, or timed out. Retry with exponential backoff. If 503s persist, check AWS Service Health for us-east-1.

SDK error handling

The TypeScript SDK throws VantageApiError:

import { VantageClient, VantageApiError } from "@vantageconnections/sdk";

try {
  await vc.websites.get("wb_does_not_exist");
} catch (err) {
  if (err instanceof VantageApiError) {
    console.log(err.status);   // 404
    console.log(err.message);  // "Website wb_does_not_exist not found"
    console.log(err.body);     // { error: "...", details: ... }
  } else {
    throw err;
  }
}

Branch on err.status (the stable signal). err.message is the human-readable message — fine for logging, less stable for programmatic switching. err.body is the parsed response body for fine-grained access to details when present.

CLI error output

The CLI prints the error message and exits with code 1. Run any command with --help to see usage if you suspect a syntax issue. Run vantage selftest first to isolate whether the problem is credentials, the API, or the specific command.

Errors

4xx — caller error

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409-ish (returned as 400 today)

429 Too Many Requests