AI agent API rate limit: सुरक्षित retries जो सीमा में रहें

Quota से टकराने वाले agent को धीमा होना चाहिए, हर अतिरिक्त प्रयास का हिसाब रखना चाहिए और समस्या बढ़ने से पहले रुक जाना चाहिए। किसी बटन पर क्लिक करने वाले व्यक्ति के लिए «विफलता पर retry करें» ठीक सलाह हो सकती है। लेकिन ऐसे process के लिए यह खतरनाक है जो किसी की निगरानी से कहीं तेज़ requests भेज सकता है।

मुश्किल कुछ सेकंड रुकने में नहीं है। असली चुनौती मूल task का अर्थ बनाए रखना है, क्योंकि पहली request provider तक पहुँचने से पहले विफल हो सकती है, provider के उसे पूरा करने के बाद connection टूट सकता है, या कई agent runs ने एक साझा allowance समाप्त कर दिया हो। सुरक्षित design इन स्थितियों को अलग करता है और human intervention को स्पष्ट outcome बनाता है, कोई शर्मनाक exception नहीं।

429 hammer करने की गलती नहीं, scheduling instruction है

HTTP 429 का मतलब है कि server request अस्वीकार कर रहा है क्योंकि client ने server द्वारा नियंत्रित अवधि में बहुत अधिक requests भेजीं। RFC 6585 इस status code को परिभाषित करता है और कहता है कि response में स्थिति समझाने वाली जानकारी होनी चाहिए तथा Retry-After header शामिल हो सकता है। यह बात महत्वपूर्ण है: 429 agent को यह नहीं बताता कि उसी request को तुरंत दोहराने से सफलता की कोई संभावना है।

Agent को पहले provider, endpoint, credential या account identity, request class, response status और rate-limit headers दर्ज करने चाहिए। फिर work को delayed state में रखना चाहिए। हर failure के बाद language model को prose में यह फैसला न करने दें। Transport layer को deterministic behavior चाहिए, क्योंकि task pressure में model अक्सर पास के किसी endpoint को आज़माएगा, filter बदलेगा या दूसरा request path बनाएगा। इससे वही refusal मिलते हुए भी calls कई गुना बढ़ सकती हैं।

Refusal अक्सर मौजूदा request से बड़े bucket पर लागू होता है। Providers limits account, project, token, IP address, endpoint family या इनके संयोजन पर लगा सकते हैं। एक agent को 429 मिल सकता है, जबकि उसी credential का इस्तेमाल करने वाला दूसरा agent कुछ समय तक काम करता रहे। इससे यह साबित नहीं होता कि पहला agent सुरक्षित रूप से retry कर सकता है। हो सकता है provider के कई buckets हों या दूसरा process बची हुई capacity इस्तेमाल कर रहा हो।

हर ज्ञात scope के लिए स्थानीय ledger रखें। यदि service per-token limit बताती है, तो requests को token के आधार पर समूहित करें। यदि केवल account-level guidance है, तो प्रमाण मिलने तक मानें कि उस account के सभी workers एक bucket साझा करते हैं। Local ledger provider के internal counter की पूरी नकल नहीं करेगा, लेकिन आपके workers को अंधाधुंध प्रतिस्पर्धा करने से रोकेगा।

IETF RateLimit Fields specification, RFC 9333, RateLimit-Limit, RateLimit-Remaining और RateLimit-Reset define करती है। ये fields quota की स्थिति बताती हैं, लेकिन पहले से मिले 429 को मिटाती नहीं हैं। इनका उपयोग future requests की गति नियंत्रित करने और provider की स्वीकार क्षमता से तेज़ी से queue भरने से बचने के लिए करें। Scope provider documentation के अनुसार समझें, क्योंकि header अकेले यह नहीं बताता कि वह एक endpoint या पूरे account पर लागू है।

एक उपयोगी state record ऐसा हो सकता है:

{
  "provider": "billing-api",
  "scope": "account:ops-team",
  "request_class": "write:invoice",
  "next_allowed_at": "2025-04-08T14:12:31Z",
  "remaining": 0,
  "reset_after_seconds": 60,
  "source": "HTTP 429 Retry-After"
}

Agent runner को अगली call भेजने से पहले यह record पढ़ना चाहिए। किसी छोटे command-line run में एक request handler के भीतर sleep करना ठीक है। कई workers, tools या resumed tasks होने पर दिखाई देने वाला next_allowed_at वाला queue बेहतर है। Scheduler तब process को व्यस्त रखने के बजाय दूसरा work चुन सकता है और operator को delay का स्पष्ट कारण दिखा सकता है।

Retry budgets छोटे failure को flood बनने से रोकते हैं

Retry budget failed call के बाद task द्वारा बनाए जा सकने वाले extra work की सख्त सीमा तय करता है। Attempts और बीता हुआ wait time, दोनों गिनें। केवल fixed count उस समय विफल होगा जब service clients से कई मिनट रुकने को कहे; केवल time limit उस समय विफल होगी जब तेज़ retry loop कुछ सेकंड में account allowance समाप्त कर दे।

हर task और हर shared provider scope के लिए अलग budgets रखें। Task budget पूछता है, «यह एक objective कितनी uncertainty सह सकता है?» Scope budget पूछता है, «सारा मौजूदा work provider पर कितना दबाव डाल सकता है?» दस tasks को तीन-तीन retries मिलें तो account को तीस extra requests फिर भी मिलेंगी। इसी तरह conservative policy burst बन जाती है।

साधारण read requests के लिए मैं छोटा budget रखता हूँ, जिसकी deadline answer की business value से कम हो। Writes के लिए blind retries पर बहुत कम budget खर्च करता हूँ। Human का इंतज़ार payment दोहराने, duplicate notices भेजने या deployment दो बार करने की लागत से कम हो सकता है।

Rule को ऐसे data के रूप में रखें जिसे agent आसानी से override न कर सके:

request_classes:
  read:
    max_attempts: 4
    max_wait_seconds: 90
    retry_statuses: [408, 429, 500, 502, 503, 504]
  idempotent_write:
    max_attempts: 3
    max_wait_seconds: 120
    retry_statuses: [408, 429, 502, 503, 504]
  uncertain_write:
    max_attempts: 1
    max_wait_seconds: 0
    retry_statuses: []
shared_scope:
  max_delayed_requests: 25
  max_concurrent_requests: 2

यह fragment एक आम failure रोकता है: agent write submit करने के बाद timeout पाता है, मान लेता है कि कुछ नहीं हुआ और ऐसे provider को फिर request भेजता है जो पहले से दबाव में है। uncertain_write class इसके बजाय status check या escalation अनिवार्य करती है। यह persistence को तब reward नहीं करती जब persistence outcome बदल सकती हो।

Budget में हर वास्तविक attempt गिनना चाहिए, libraries द्वारा शुरू किए गए retries भी। मैंने application में retry controls देखे हैं, जबकि HTTP client, workflow runner और proxy, तीनों नीचे से retry कर रहे थे। तीनों के defaults देखने तक request count रहस्यमय लगती रही। Retries की जिम्मेदारी एक layer को दें। बाकी layers को बिना retry किए errors ऊपर भेजने के लिए configure करें, या उनका behavior स्पष्ट करें और total budget में शामिल करें।

Budget समाप्त होने पर generic failure नहीं, context वाला terminal result दें। Result में बताएं कि original request भेजी गई थी या नहीं, response आया या नहीं, कितने attempts हुए, task ने कितना इंतज़ार किया और अगला सुरक्षित action क्या है। तब agent असंबंधित work जारी रख सकता है या सटीक escalation दिखा सकता है, बजाय खुद से बार-बार «फिर कोशिश करो» कहने के।

Backoff में jitter और ceiling दोनों चाहिए

Exponential backoff repeated refusal के बाद attempts के बीच delay बढ़ाकर pressure घटाता है। Jitter एक साथ विफल हुए workers को synchronized wave में लौटने से रोकता है। दोनों client में होने चाहिए, भले provider reset time प्रकाशित करता हो, क्योंकि internal concurrency अपना thundering herd बना सकती है।

Attempt number n के लिए, जहाँ पहली retry n = 1 है, cap निकालें और उसके भीतर random delay चुनें:

import random

BASE_SECONDS = 1.0
MAX_SECONDS = 60.0

def retry_delay(attempt_number: int) -> float:
    cap = min(MAX_SECONDS, BASE_SECONDS * (2 ** attempt_number))
    return random.uniform(0, cap)

यह full jitter है। इससे हर worker का ठीक 2, 4, 8 और 16 seconds सोना टलता है। Fixed delays लोकप्रिय हैं क्योंकि logs पढ़ना आसान होता है। लेकिन उनसे coordinated retries का अनुमान लगाना भी आसान हो जाता है, जो busy service के लिए ठीक उलटा है।

जब response में Retry-After हो, तो वह locally calculated shorter delay पर प्राथमिकता रखता है। RFC 9110 के अनुसार Retry-After seconds में delay या HTTP date, दोनों हो सकता है। दोनों forms parse करें। यदि machine clock और provider clock अलग होने से date पहले ही बीत चुकी हो, तो tight loop में retry करने के बजाय छोटा minimum delay लगाएँ।

Backoff को rate pacing का विकल्प न मानें। Backoff failure के बाद शुरू होता है। Token bucket, leaky bucket या simple scheduler limit failure से पहले rate नियंत्रित करता है। यदि provider ज्ञात interval में requests की ज्ञात संख्या अनुमति देता है, तो published allowance से नीचे requests pace करें और interactive work के लिए capacity बचाकर रखें। Scheduler को concurrency भी सीमित करनी चाहिए। बीस simultaneous requests किसी worker के RateLimit-Remaining response पढ़ने से पहले ही short interval की capacity खा सकती हैं।

एक व्यावहारिक dispatch rule सरल है: call भेजने से पहले shared scope का next allowed time और उपलब्ध concurrency slot जाँचें। 429 के बाद कोई retry schedule करने से पहले scope record update करें। यह क्रम महत्वपूर्ण है। यदि workers refusal publish करने से पहले retries schedule कर दें, तो हर worker समझ सकता है कि अगला slot उसी का है।

Delay और total wait, दोनों cap करें। Uncapped exponential curve task को घंटों तक टाल सकती है और assumptions समाप्त होने के बाद भी stale run जीवित रख सकती है। Deadline के बाद agent को task fail करना चाहिए या scheduler को सौंपना चाहिए, और बाद की review के लिए original input सुरक्षित रखना चाहिए।

Retry सुरक्षित है या नहीं, यह idempotency तय करती है

Idempotent request दोहराए जाने पर वही intended effect पैदा करती है। इसका मतलब यह नहीं कि HTTP PUT इस्तेमाल करने वाली हर request हर application में harmless है, और न यह कि हर POST खतरनाक है। RFC 9110 PUT और DELETE जैसे methods को intent के स्तर पर idempotent बताता है, जबकि POST सामान्यतः idempotent नहीं है। Operational risk provider के वास्तविक API contract पर निर्भर करता है।

Read requests आम तौर पर retry सह लेती हैं, बशर्ते agent यह स्वीकार करे कि लौटाया गया data बदल चुका हो सकता है। Delete request भी retry सह सकती है, यदि पहले से गायब resource को delete करने पर ज्ञात और स्वीकार्य result मिले। Payment, invitation, support ticket, purchase order या deployment बनाना blind repetition सहन नहीं करता। Timeout या connection reset के बाद इन calls पर सबसे अधिक सावधानी चाहिए।

यह क्षेत्र अक्सर दो अलग स्थितियों को मिला देता है:

• जो request provider तक पहुँची ही नहीं, उसे resend करना सुरक्षित है, यदि operation खुद इसे अनुमति देता हो।
• जिस request का outcome अज्ञात है, उसमें दूसरा side effect भेजने से पहले reconciliation चाहिए।

Client द्वारा bytes लिखने के बाद connection failure यह साबित नहीं करता कि provider ने action नहीं किया। Server ने operation पूरा कर दिया हो सकता है और response connection खो गई हो। Response न मिलने से agent outcome नहीं निकाल सकता।

Provider idempotency key support करता हो तो हर logical action के लिए एक स्थिर token बनाएँ और उसी action की हर retry में उसे reuse करें। हर attempt पर नया token न बनाएँ। नया token provider को बताता है कि हर retry अलग operation है, जिससे protection बेअसर हो जाती है।

POST /v1/transfers HTTP/1.1
Idempotency-Key: transfer-7c41b5b9-7f5b-4f51
Content-Type: application/json

{"source":"acct_17","destination":"acct_42","amount":12500,"currency":"USD"}

पहली call भेजने से पहले token को task और request payload के साथ store करें। Runner restart होने पर उसे वही token recover करना चाहिए। Provider का returned operation identifier भी store करें। बाद में reconciliation call उस identifier से original action की स्थिति पूछ सकती है, उसे फिर से बनाए बिना।

यदि API idempotency सुविधा नहीं देता, तो create-then-query pattern देखें। Agent payload में client-generated external reference जोड़ सकता है, फिर uncertain failure के बाद उसी reference से search कर सकता है। यदि API न idempotency देता है, न reliable lookup, तो repeated writes automate न करें। Provider records की जाँच के लिए human चाहिए। यह तब तक धीमा लगता है, जब तक duplicate side effect ऐसे system में न पहुँच जाए जिसे साफ़-साफ़ undo न किया जा सके।

Rate limits को outages और bad requests से अलग रखें

हर non-success status को एक जैसा मानने वाली retry policy defects छिपाएगी और quota बर्बाद करेगी। Delay चुनने से पहले response classify करें। Status code, response body, provider error code और request method, सभी महत्वपूर्ण हैं।

व्यावहारिक विभाजन:

• 429 का अर्थ है गति घटाएँ, provider guidance मानें और shared rate-limit budget से charge करें।
• 408, connection resets और कुछ 5xx bounded retry के योग्य हो सकते हैं, लेकिन write operations को फिर भी idempotency या reconciliation path चाहिए।
• 400, 401, 403, 404 और 422 में आम तौर पर corrected request, बदला हुआ authorization या human decision चाहिए। इन्हें दोहराना बेकार है।
• 409 के लिए resource-specific handling चाहिए। इसका मतलब duplicate, version conflict या दूसरे workflow का lock हो सकता है।
• Provider-specific quota-exhausted error के लिए billing या daily reset तक इंतज़ार करना पड़ सकता है, जो short burst limit से अलग है।

503 Service Unavailable को 429 का interchangeable रूप न मानें। 503 कहता है कि service उस समय request serve नहीं कर सकती; 429 कहता है कि client ने limit पार कर दी। दोनों में Retry-After हो सकता है, लेकिन 429 से affected scope के लिए scheduler को local throughput घटाना चाहिए। 503 regional, endpoint-specific या provider-wide हो सकता है। Metrics और operator messages में यह अंतर बनाए रखें।

Agent behavior invalid-request storms भी पैदा कर सकता है। 422 मिलने के बाद model unsupported filter के साथ endpoint को बार-बार call कर सकता है, या credential revoke होने के बाद 401 retry कर सकता है। Repeated identical failures के चारों ओर circuit breaker रखें। उदाहरण के लिए, एक run में वही endpoint, method और normalized error code कई बार fail हो तो path रोक दें और error details को constraint के रूप में agent को लौटाएँ। उसे whitespace बदलने, JSON fields का क्रम बदलने और इसे नए options की खोज बताने की अनुमति न दें।

Normalized request fingerprint में secrets और volatile headers न रखें। Method, endpoint template, stable payload fields और API error code शामिल करें। इससे credentials या पूरी sensitive bodies log किए बिना runner loop पहचान सकता है।

Shared credentials को polite agents नहीं, एक queue चाहिए

Shared API credential coordination problem बनाता है जिसे individual agents अच्छे इरादों से हल नहीं कर सकते। हर process केवल अपनी requests देखता है, जब तक scheduler common budget न दे। Per-agent backoff burst की संभावना घटाता है, लेकिन scarce account-wide quota को उचित रूप से बाँटता नहीं।

Shared credential scope के सामने outbound queue रखें। Priority जानबूझकर तय करें। Human-approved production change को background inventory work पर प्राथमिकता चाहिए हो सकती है। दस हज़ार records खोजने वाला long-running agent उन्हें provider की अनुमति वाली गति से page करे, बजाय एक साथ हर page request queue में भरने के।

Queue में cancellation होना चाहिए। Parent task समाप्त हो जाए तो उसकी delayed requests जागने से पहले discard करें। वरना stopped task बाद में भी quota खा सकता है और audit trail confusing बना सकता है। Cancellation को reserved concurrency slot भी release करना चाहिए।

Safe reads के लिए request coalescing rule अपनाएँ। यदि पाँच agent runs कम अंतराल में उसी immutable record के लिए पूछें, तो एक request करें और result सभी waiting tasks को दें। Freshness अर्थ बदलती हो, जैसे balance या approval status, तो reads coalesce न करें। उद्देश्य accidental duplicates हटाना है, ऐसा cache बनाना नहीं जो decision लेने वाले agent को stale facts दे।

Rate limits अक्सर planning की गहरी समस्या दिखाती हैं। Agent हर item के लिए detail endpoint call करके instructions का सही पालन कर सकता है, फिर भी गलत access pattern इस्तेमाल कर रहा हो। Retries जोड़ने से पहले batch endpoints, pagination controls, conditional requests, webhooks, export jobs या server-side search endpoint देखें। ये बदलाव provider को refuse करने की नौबत आने से पहले calls घटाते हैं।

Sallyport credentials को agent process से बाहर रखते हुए individual outbound calls record कर सकता है, लेकिन caller को फिर भी queueing और retry controls चाहिए। Credential separation secret exposure घटाता है, provider का quota नहीं बदलता।

Human escalation को uncertainty सुरक्षित रखनी चाहिए

जब system यह तय न कर सके कि side effect हुआ या नहीं, remaining wait task deadline से आगे हो, shared quota समाप्त हो या repeated limits account configuration problem की ओर इशारा करें, तब human को जिम्मेदारी दें। Escalation कोई generic «API failed» notification नहीं है। यह ऐसी compact case file होनी चाहिए जिससे कोई scattered logs दोबारा पढ़े बिना निर्णय ले सके।

Operator को ये facts भेजें:

• task का requested outcome और रुका हुआ exact logical action;
• provider, endpoint, method, account scope और sanitized request fingerprint;
• attempt timestamps, statuses, Retry-After या rate-limit headers और खर्च हुआ budget;
• operation के पास idempotency token, provider operation ID या reconciliation query है या नहीं;
• अगले सुरक्षित विकल्प, जैसे wait, status query, quota बढ़ाना, plan बदलना या cancel करना।

Approval card में default रूप से raw request body न रखें। उसमें personal data, internal documents या ऐसा value हो सकता है जो गलत व्यक्ति तक पहुँचने पर संवेदनशील बन जाए। संक्षिप्त summary दिखाएँ और detailed access को जानबूझकर किया जाने वाला audit action रखें।

Approval में केवल «continue» की सहमति न माँगें, decision माँगें। Uncertain write के लिए «existing operation query करें», «उसी idempotency token से retry करें», «cancel करें» और उचित होने पर «नई operation भेजें» जैसे विकल्प दें। अंतिम विकल्प साफ़ बताए कि इससे दूसरा side effect पैदा हो सकता है। जब choices वास्तविक risk बताती हैं, लोग बेहतर निर्णय लेते हैं।

Continued access की approval और किसी particular external action की approval अलग controls हैं। Session authorized रह सकता है, फिर भी payment, production write या limit event के बाद repeated request के लिए per-call review चाहिए। Interface और log, दोनों में इन decisions को अलग रखें।

Escalation की समीक्षा करते समय reconciliation से शुरू करें। Idempotency key, external reference या operation identifier से provider को query करें। Retry तभी करें जब query completed action न दिखाए या provider duplicate suppression की गारंटी दे। Blind resend से यह एक network round trip धीमा है, लेकिन downstream ledger में पहुँचे duplicate को सुधारने से तेज़ है।

Audit records में attempted action और wait दोनों दिखने चाहिए

उपयोगी audit record केवल «क्या request ने 200 लौटाया?» का उत्तर नहीं देता। उसमें दिखना चाहिए कि agent ने क्या करने की कोशिश की, किस authorization ने उसे अनुमति दी, remote service ने क्या लौटाया और retry controller ने कैसी प्रतिक्रिया दी। Decision record के बिना calls की sequence careless repetition जैसी लग सकती है, भले scheduler ने documented Retry-After का पालन किया हो।

Dispatch से पहले एक event record करें, फिर result और scheduling events append करें। Request metadata में plaintext credentials न रखें। एक compact sequence ऐसा हो सकता है:

14:11:02 action_requested  task=sync-482 method=POST route=/records
14:11:02 action_sent       attempt=1 idempotency=rec-91f2
14:11:03 action_result     status=429 retry_after=30 scope=account:ops
14:11:03 retry_scheduled   attempt=2 due=14:11:33 budget_wait=30
14:11:33 action_sent       attempt=2 idempotency=rec-91f2
14:11:34 action_result     status=201 provider_id=r_893

यह sequence logical action और transport attempts को अलग करती है। Human पूछे कि दो POST calls क्यों हुईं, तो record दिखाता है कि दोनों में एक ही idempotency token था और provider-directed delay का पालन हुआ। यदि दूसरी response timeout हो जाती, तो अगला event reconciliation_required होना चाहिए था, दूसरा automatic action_sent नहीं।

Tamper-evident logging incident review में व्यावहारिक लाभ देती है: team जाँच सकती है कि run ने बाद में असुविधाजनक attempts मिटाए नहीं। Sallyport अपने session और call journals को encrypted hash-chained audit log से project करता है, और sp audit verify vault key के बिना offline chain जाँचता है। इससे operator provider throttle, agent loop और देर से हुए manual retry में अंतर कर सकता है।

Logs को retention और access boundaries भी चाहिए। Request path, provider account identifier और timing pattern token के बिना भी sensitive operational activity प्रकट कर सकते हैं। Decision reconstruct करने जितना data capture करें, फिर यह सीमित करें कि record कौन search और export कर सकता है।

Production में मिलने से पहले failure paths test करें

Rate-limit design तब तक पूरा नहीं है जब तक test यह साबित न करे कि वह calls रोकता है, idempotency बनाए रखता है और uncertainty पर escalation करता है। केवल एक 429 mock करना काफी नहीं। Concurrent workers और ऐसी failures चाहिए जो remote service के action करने के बाद हों।

Test environment या controllable fake API पर यह sequence चलाएँ:

1. एक simulated account scope का उपयोग करने वाले तीन agent tasks शुरू करें और वही safe read request भेजें।
2. पहली request को Retry-After: 10 के साथ 429 लौटाएँ। जाँचें कि scheduler उस scope का पूरा work delay करता है, बजाय बाकी दो को full speed पर चलने देने के।
3. Delay के बाद success लौटाएँ और जाँचें कि retry times में थोड़ा अंतर है, वे एक burst की तरह साथ नहीं आईं।
4. Stable idempotency token के साथ write भेजें, record store होने के बाद fake API में connection drop simulate करें और जाँचें कि runner नया create भेजने के बजाय status query करता है।
5. Configured time budget समाप्त करें और जाँचें कि operator को sanitized escalation record मिलता है तथा canceled work बाद में जागकर जारी नहीं होता।

Fake API पर outbound attempts मापें, केवल agent के भीतर function calls नहीं। Internal counters HTTP libraries या wrappers द्वारा जोड़े गए retries छोड़ देते हैं। Restart भी test करें: पहली uncertain write के बाद runner रोकें, persisted state restore करें और confirm करें कि वह original idempotency token के साथ reconciliation resume करता है।

Agent test harness को केवल success response पाने के लिए reward न दें। सही संख्या में calls करने, निर्देश मिलने पर रुकने और evidence मिलने तक ambiguous write unresolved रखने के लिए reward दें। External actions duplicate करके «काम पूरा» करने वाला agent test पास नहीं हुआ है।

सबसे पहला control explicit terminal outcomes वाला shared retry budget होना चाहिए। यह rate limiting को लगातार कोशिश करने के निमंत्रण से बदलकर record, deadline और remote state uncertain होने पर हस्तक्षेप कर सकने वाले व्यक्ति वाला operational decision बना देता है।