Error handling

The API uses conventional HTTP status codes plus a machine-readable error object. This guide covers how to react to each failure class correctly - especially retries, which are easy to get dangerously wrong.

Error shape

{
  "error": {
    "type": "invalid_request",
    "code": "parameter_missing",
    "message": "Missing required parameter: name.",
    "param": "name",
    "request_id": "req_8fK2mPx4vL",
    "docs_url": "https://docs.meridian.dev/docs/api/errors#parameter_missing"
  }
}

Status code map

Idempotent retries

The dangerous retry is repeating a write that actually succeeded server-side - e.g. the response was lost to a network reset. POST requests accept an Idempotency-Key header: repeat the same key within 24 hours and you get the original response instead of a duplicate operation.

curl -X POST https://api.meridian.dev/v2/projects \
  -H "Authorization: Bearer $MERIDIAN_API_KEY" \
  -H "Idempotency-Key: provision-acme-2026-09-17-001" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-import", "region": "us-east"}'

// SDKs attach an idempotency key to every create/update call automatically.
const project = await client.projects.create(
  { name: "acme-import", region: "us-east" },
  { idempotencyKey: "provision-acme-2026-09-17-001" } // optional override
);

Retry policy

The recommended pattern for 429 and 5xx - and what every official SDK does by default:

attempt 1: fail → wait min(2^1, 30)s + jitter → retry
attempt 2: fail → wait min(2^2, 30)s + jitter → retry
attempt 3: fail → wait min(2^3, 30)s + jitter → give up, surface error

• Honor Retry-After on 429 when present - it overrides your computed delay.
• Add jitter (±50%) to avoid thundering-herd retries across your fleet.
• Cap attempts at 3–4; beyond that you're amplifying an outage.
• Log request_id on every failure - it's the trace key for support.

const client = new Meridian(key, {
  maxRetries: 3,          // default
  timeout: 30_000,        // ms per attempt
});

Rate limits

Limits are per environment: 600 req/min in test, 5,000 req/min in live, evaluated on a rolling window per key.

Every response carries:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1758092460

At 429 you also get Retry-After (seconds). Sustainable pacing beats reactive retrying - if Remaining runs low, queue writes.

Defensive patterns

Validate locally first. Type errors and missing params are cheaper caught client-side - SDKs validate required fields before sending.

Distinguish transient from permanent. Wrap SDK calls and classify:

import { MeridianError } from "@meridian/sdk";

try {
  await client.projects.create({ name: "x", region: "us-east" });
} catch (e) {
  if (e instanceof MeridianError) {
    if (e.status === 429 || e.status >= 500) {
      // transient - safe to retry
    } else if (e.code === "parameter_missing") {
      // permanent - fix the call, don't retry
    }
    console.error(e.requestId); // always log the trace id
  }
}

Never retry 4xx blindly. 400/401/403/404/422 fail deterministically - retrying just repeats the mistake.

Common error codes