Understanding API limitations and specifications helps you optimize performance, plan capacity, and avoid throttling. This guide covers rate limits, driver capabilities, request constraints, and best practices.
Overview Nimble’s API implements tiered specifications based on:
Driver selection : Different drivers have different rate limitsRequest complexity : Complex operations may have additional constraintsResource usage : Fair usage policies ensure platform stability
Drivers Nimble offers different drivers optimized for various use cases:
Driver Description Best For vx6HTTP requests without rendering Static pages, simple HTML vx8JavaScript rendering Dynamic content, AJAX vx10Stealth browser mode Protected sites, complex sites
Each driver has different pricing and rate limits. Higher-tier drivers cost more per request.
Rate Limits Default rate limits by driver All accounts have the following default rate limits:
Driver Rate Limit vx6, vx8, vx1083 QPS (5,000 QPM)
Need higher limits? Reach out to your CS or open a via a Support Ticket to discuss custom rate limits based on your requirements.Agent generation Custom agent generation has a separate daily limit:
Endpoint Limit POST /v1/agents/generations100 generations per customer / day
This limit applies across all generation methods (API, CLI, SDK, and the Agent Builder skill). It covers both new agent creation and refinement via from_agent. See Agent Creation for details.
Every response includes metadata headers:
ratelimit-limit: 20 ratelimit-remaining: 15 x-task-id: 8e8cfde8-345b-42b8-b3e2-0c61eb11e00f
Use these headers to:
Monitor rate limit usage
Track request IDs for debugging
Optimize driver selection
Measure performance
Handling rate limits When you exceed rate limits, the API returns a 429 status code:
{ "status" : "failed" , "msg" : "Rate limit exceeded" }
Best practices:
Implement exponential backoff on 429 responses
Use the retry_after value to schedule next request
Monitor rate limit headers in responses
Batch requests when possible
Use lower-tier drivers when sufficient
HTTP status codes Success codes Code Status Description 200 OK Request succeeded and data was returned successfully
Client error codes Code Status Description 400 Bad Request Invalid URL, malformed parameters, or missing required fields 401 Unauthorized Account doesn’t exist, invalid API key, or missing credentials 402 Payment Required No budget, limit reached, trial expired, or trial quota finished 403 Forbidden Account blocked or not activated 429 Too Many Requests Rate limit exceeded for your plan
Server error codes Code Status Description 500 Internal Server Error Unexpected server-side error occurred 501 Not Implemented Proxy service encountered an error 555 Request Timeout Request exceeded maximum execution time
Nimble automatically retries failed requests before returning a final failure status (500)
Blocked Domains The following domains are blocked across all Web APIs and Proxy services. Requests targeting these domains will be rejected.
*.paypal.comaccount.sonyentertainmentnetwork.comacopic.clickadskpak.comamctheatres.comandromedabee.comantliabee.co.ukapi.groupon.comapi.stripe.comapi.tyrads.comapusbee.co.ukauth.api.sonyentertainmentnetwork.combellarmine.clickcaixa.gov.brcallofduty.comcanal-plus.comclubmium.comclubmium.netcouponcabin.comcrunchyroll.comdazn.comdirectv.comea.comepicgames.comfustian.clickgomobile.itgooglecm.hit.gemius.plhbo.comhitspro.nethoneyga.inhoneygain.comhoneygain.moneyhotstar.comiplogger.orgkayak.commojang.commte.gov.brmusic-box.mobimybip.itmyy.ionative.np.ac.playstation.netnetworkcontroller.netocmey.comonevanilla.comordo.linkpagseguro.compaypal.complaystation.complaystation.netplex.tvpowerbrowsing.onlinerevenuevelocity.euroblox.comrunescape.comseasyvendas.comsky.comsport4life.mobispotify.comssfcu.comsteamcommunity.comsteampowered.comtorrentdownloads.mettvnw.nettyrads.comtyrrewards.comubi.comubisoft.comunrealengine.comusps.comvaluedopinions.comvrv.cowellsfargo.comwww.ltv-mob.comyogini.topzelator.in 
