Грешки, квоти и ограничения
Обработвайте коректно повторните опити, квотите, ограниченията на честотата и изтеклото време.
Всички неуспешни заявки използват единен JSON формат. Грешките при задачите за отговор се връщат в данните за самата задача, а не чрез HTTP код за грешка.
Формат на грешките
{
"detail": {
"code": "rate_limit_exceeded",
"message": "Per-minute rate limit exceeded for your plan."
}
}При неуспешна валидация FastAPI връща HTTP 422 с подробности за съответните полета. Тези грешки са постоянни и изискват корекция на заявката.
Политика за повторни опити
| HTTP | Примерен код | Повторен опит? | Препоръчително действие |
|---|---|---|---|
401 | invalid_api_key | Не | Заменете или коригирайте ключа. |
403 | key_limit_reached | Не | Отменете ключ или променете плана. |
404 | document_not_found | Не | Проверете дали двойката идентификатори идва от търсене. |
422 | invalid_request | Не | Коригирайте полетата или комбинацията от филтри. |
429 | rate_limit_exceeded | Да | Изчакайте според Retry-After и добавете малко случайно отклонение. |
429 | monthly_quota_exceeded | Не | Спрете натоварването, докато има нова квота. |
429 | overage_limit_exceeded | Не | Увеличете месечния лимит за доплащане или изчакайте следващия календарен месец по UTC. |
503 | quota_service_unavailable | Да | Повторете след указаното време, като увеличавате интервала между опитите. |
500 | search_failed | Внимателно | Единицата се възстановява; използвайте ограничен брой опити. |
Увеличавайте интервала между опитите експоненциално, добавяйте малко случайно отклонение и ограничете общия брой опити. Не повтаряйте непроменена заявка след 401, 403, 404 или 422.
Лимити за минута
Всяка крайна точка, удостоверена с API ключ, има ограничение на броя заявки за минута. Успешният отговор включва X-RateLimit-Limit. Когато текущият екземпляр на услугата отхвърли заявка поради това ограничение, API връща Retry-After в секунди.
В бета версията ограничението се прилага самостоятелно от всеки екземпляр на услугата. Поради това действителният общ лимит може да е по-висок от обявения за плана. Не разчитайте на тази особеност — управлявайте трафика си според публикуваната стойност.
Месечна квота
Търсенията, извличането на документи и отговорите имат отделни месечни квоти, които се отчитат общо за всички API ключове в профила. GET /v1/usage връща текущото потребление, лимитите и натрупаната сума за допълнително потребление за календарния месец по UTC.
Единицата от квотата се отчита атомарно преди началото на ресурсоемката операция. При неуспешно търсене, извличане или създаване на отговор тя се възстановява. Ако услугата за отчитане не е достъпна, API връща 503, вместо да изпълни операция, която не може да бъде отчетена.
Допълнителното потребление е изключено по подразбиране. Клиентите с активен план Launch или Scale могат да го включат от страницата за API достъп и да определят максимална сума за доплащане за месеца. Към Stripe се подават само успешно изпълнените заявки над включените количества; неуспешните операции не се отчитат и не се таксуват.
Време за изчакване и дублирано изпълнение
- Осигурете поне 60 секунди за синхронно търсене.
- Проверявайте задачите за отговор, вместо да държите заявка отворена.
- Ако задачата за отговор не приключи в рамките на 15 минути, тя се отбелязва като неуспешна и използваната единица от квотата се възстановява.
- API все още не поддържа ключове за идемпотентност. Ако клиентът не получи отговора след приемане на заявката, автоматичното повторение може да доведе до дублирано изпълнение.
При пакетни интеграции записвайте собствен корелационен идентификатор заедно с върнатия job_id, ограничете броя на паралелните заявки и сравнявайте потреблението преди и след изпълнението.