Reference

Error codes

Every Meridian API response includes a machine‑readable error.code field. Use this reference to diagnose failures and recover quickly.

Code	Name	What it means at Meridian	Remediation
401	Unauthorized	Your API key is missing, expired, or was revoked. Meridian requires a valid Bearer token on every request.	Generate a fresh key from your dashboard → API Keys. Confirm the Authorization header reads Bearer sk_live_… (not sk_test_…). If the key was just created, wait up to 60 seconds for propagation.
402	Payment Required	Your subscription is past due or your on‑demand credit balance is exhausted. Meridian blocks all endpoints except billing when payment fails.	Visit Billing → Invoices and settle the outstanding amount. If you pay via invoice (NET‑30), ensure the remittance email matches your account email exactly.
403	Forbidden	The key is valid but lacks the scope needed for this endpoint. Example: a read‑only key hitting POST /v1/agents.	Check the key’s scope column in the dashboard. For write operations, use a key with the agent:write or admin scope. Do not share admin keys in client‑side code.
404	Not Found	The resource ID in the URL does not exist or belongs to a different workspace. Meridian never discloses whether a resource exists for security reasons.	Verify the UUID in the path. If you switched workspaces, confirm the resource lives under the current workspace ID. Use GET /v1/workspaces to list available workspaces.
422	Unprocessable Entity	The request body failed validation. This is typically a malformed JSON payload, a missing required field, or a value outside allowed ranges.	Read the error.details array in the response — it lists every failing field and the expected format. Validate payloads against the OpenAPI spec at docs.meridian.local before sending.
429	Too Many Requests	You exceeded the rate limit for your plan. Meridian enforces per‑key, per‑endpoint windows (default 60 req/min for Starter, 600 for Pro).	Check the Retry-After header for the cooldown in seconds. Implement exponential backoff with jitter. Upgrade to Pro or contact support for a temporary burst allowance.
500	Internal Server Error	An unexpected condition on Meridian’s side. This is never your fault. Our on‑call engineer is paged automatically.	Retry with exponential backoff (start at 1 s, cap at 30 s). If the error persists beyond 5 minutes, check status.meridian.local for an active incident and subscribe to updates.
502	Bad Gateway	An upstream provider (inference backend, vector store) returned an invalid response. Meridian’s API gateway cannot fulfil the request.	Retry once after 2 seconds. If the error repeats, the upstream may be degraded — check our status page. No action is needed on your side.
503	Service Unavailable	Meridian is temporarily down for maintenance or under excessive load. The load balancer has no healthy targets.	Wait for the Retry-After window (typically 30–120 seconds). For planned maintenance, we announce windows 48 hours in advance on status.meridian.local and via email.

Still seeing an error? Contact support with your request ID and we will respond within 15 minutes for production incidents.