Markdown API errors

Error response shape

All errors — whether validation, authentication, rate limiting, or server-side — serialise identically:

{
  "error": {
    "code": "bad_request",
    "message": "Invalid request body.",
    "details": {
      "fieldErrors": {
        "markdown": [
          "Required"
        ]
      }
    }
  }
}

• code — stable identifier; switch on this.
• message — human-readable; don't pattern-match against it.
• details — optional structured payload (eg. field-level validation errors).

Defensive error handling

A robust client checks the HTTP status, parses the JSON envelope, and decides whether to retry, surface a UI error, or escalate:

async function call(path: string, body: unknown, apiKey: string) {
  const res = await fetch(`https://trymarkdownviewer.com${path}`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  const payload = await res.json();
  if (!res.ok) {
    const code = payload?.error?.code ?? "unknown_error";
    // Switch on the stable code, not res.status alone.
    switch (code) {
      case "rate_limited":
      case "quota_exceeded":
        // Honour Retry-After or upgrade plan.
        throw new Error(`Rate limited: ${code}`);
      case "unauthorized":
        // Force a key refresh / logout.
        throw new Error("Auth failed");
      default:
        throw new Error(`${code}: ${payload?.error?.message}`);
    }
  }
  return payload.data;
}

Error code reference

Every error you can see, in one table. The codes are sorted client → rate → server.

FAQ

What does the error.code field mean?+

It's a stable, machine-readable identifier for the failure (eg. unauthorized, rate_limited, payload_too_large). Build your conditionals against the code — the human-readable error.message can change between versions without warning.

How do I tell a burst rate limit from a quota exhaustion?+

Both return HTTP 429, but error.code differs. rate_limited means you tripped the per-key 20 req / 10s burst limit. quota_exceeded means your plan's daily or monthly quota has been used up — wait for X-RateLimit-Reset or upgrade.

When should I retry a failed request?+

Retry idempotent 5xx errors (internal_error, timeout) with exponential backoff. Always honour the Retry-After header on 429 responses. Don't retry 4xx errors — they're client-side and won't fix themselves.

Are error responses still rate-limited?+

Failed requests count toward burst limits but do not consume your plan quota — bad_request, unauthorized, and validation errors won't drain your daily allowance.

How do I get more context on a validation failure?+

When the error code is bad_request, look at the details.fieldErrors object. It's a map of field name → array of validation messages so you can show the user a precise inline error.