Nimble

Nimble Documentation Audit

Nimble's docs are broad, agent-friendly (llms.txt, llms-full.txt, per-page Markdown, downloadable OpenAPI 3.1 spec) and rich in multi-language examples — but the two pages that document the same API fundamentals (status codes, rate limits, 429 bodies) contradict each other, a published SDK example crashes with a TypeError, and the July v2 rename left "agent" meaning two different products in different corners of the site.

1. Two contradictory 429 error bodies for the same API (critical)

Location: https://docs.nimbleway.com/api-reference/introduction and https://docs.nimbleway.com/nimble-sdk/admin/rate-limits

Problem: The API Introduction documents the rate-limit error as a structured envelope: {"error": {"code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Current limit: 83 QPS", "retry_after": 2}}. The Rate Limits page documents the same 429 response as a flat, differently-shaped body: {"status": "failed", "msg": "Rate limit exceeded"}. Worse, the Rate Limits page's own best practices say "Use the retry_after value to schedule next request" — a field that does not exist in the body shown three lines above it.

Consequence: Anyone writing backoff logic — human or coding agent — must parse one of these shapes. One of them is wrong, so retry code built from the wrong page silently reads undefined and falls back to blind exponential backoff, or crashes on a missing key. Agents fail silently here; they can't judge which page is authoritative.

The fix: Capture a real 429 response from sdk.nimbleway.com/v2, publish that single body on both pages (or better, in the OpenAPI spec as a 429 response schema), and delete the other version. If retry_after exists, show it in the body; if not, remove the best-practice line that references it.

2. Python SDK Map example crashes with TypeError (critical)

Location: https://docs.nimbleway.com/nimble-sdk/sdks/python (Core Methods → Map)

Problem: The example is client.map(URL="https://www.example.com", sitemap="only") with an uppercase URL keyword. The actual published package (pip install nimble_python, verified by introspection: inspect.signature(client.map) → ['url', 'country', 'domain_filter', 'limit', 'locale', 'sitemap', ...]) accepts lowercase url only. Every other Map example on the site — the Quickstart () and the Map guide itself — uses lowercase.