icanhazdadjoke

Gotchas & limits

• Omitting `Accept: application/json` does not error — it silently serves `text/plain` (or HTML for a browser's default Accept) instead of JSON, confirmed live against the same URL with no header.
• GET /j/{id} fetches one specific joke by id; a nonexistent id still returns a clean JSON body at HTTP 200, with 404 appearing only in the body's own `status` field — confirmed live on two separate bad ids, e.g. /j/doesnotexist12345 returned HTTP 200 with {"message":"Joke with id \"doesnotexist12345\" not found","status":404}. Check the body, not the status code — a genuinely bogus path outside /j/ does return a real HTTP 404, so the host is not masking statuses generally.
• GET /search accepts `term`, `page`, and `limit` (default 20, max 30 per the docs) query parameters and wraps matches in a paginated shape (`current_page`/`next_page`/`results`/`total_jokes`) that differs entirely from the single-joke shape — confirmed live against /search?term=cat&limit=1.
• The API is rate-limited per IP to a fixed ~60-second window, anchored at the first request of the window rather than rolling forward with each call: live response headers carried `x-ratelimit-limit: 100` and a decrementing `x-ratelimit-remaining`, while `x-ratelimit-reset` stayed pinned to one value for the whole window — across four requests 8 seconds apart it held at 1785105280 while the distance to it shrank 61s, 53s, 45s, 37s. Once it elapsed, the next request opened a fresh window with `remaining` back at 99. The anchor is not a wall-clock minute boundary either (1785105280 % 60 == 40). None of this is written down anywhere in the API's own docs — the headers are the only source.
• GET /j/{id}.png renders the same joke as a shareable image rather than JSON — useful for embedding, not for programmatic consumption.