Руководство по квотам и ограничениям частоты запросов

Ежедневно FedEx получает тысячи запросов API. Для обработки такого большого объема мы используем три метода регулирования нагрузки. Квоты, ограничения частоты запросов и пороговые значения позволяют эффективно распределять ресурсы FedEx.

Квоты применяются на уровне организации и проекта API.

Квоты на организацию

Квота — это максимально допустимое количество запросов API от организации в день. Таким образом, потребители API должны учитывать общее число запросов API, отправляемых в рамках всех проектов организации. Запросы учитываются независимо от объема данных, полученных от API FedEx в ответ.

Пример. Для организации установлена квота 500 000 запросов API в день. Если организация отправит 500 000 запросов за первые несколько часов, она исчерпает данную квоту. До истечения суток на все запросы будет отправляться код ошибки «429 Too many requests — Daily transaction quota exceeded. Retry after 12:00AM GMT» (429 Слишком много запросов — превышена дневная квота транзакций. Повторите попытку после 0:00 [GMT]).

Квоты на проект API

Эта квота применяется на двух уровнях: проекта и возможностей.

Что такое возможности?

API можно разделить на группы в зависимости от доступных возможностей. Каждая группа возможностей представляет собой пакет из одной или нескольких конечных точек. Например, возможность API отслеживания имеет шесть конечных точек API, а возможность проверки адресов — только одну.

Для функции отслеживания используемая по умолчанию квота за каждую возможность на проект (Per Capability Per Project, PCPP) составляет 100 000 запросов в день. Это значит, что, если трафик любого из проектов организации в адрес любой из 6 конечных точек для данной возможности превысит установленный лимит, до конца дня вы будете получать сообщение об ошибке «429 Too many requests» (Слишком много запросов). Это относится ко всем последующим запросам на отслеживание для любой из этих 6 конечных точек.

Пример. Если для возможности отслеживания (с 6 конечными точками) в проекте действует квота 100 000, в нее будет засчитываться общее количество транзакций для всех 6 конечных точек. Если проект превысит этот лимит, то до истечения суток до 0:00 (GMT) для всех последующих операций отслеживания система будет выдавать сообщение об ошибке «429 — Too many requests — Daily transaction quota exceeded» (429 Слишком много запросов — превышена дневная квота транзакций).

Ограничение частоты запросов

Для каждого проекта установлено ограничение в 1400 транзакций за 10 секунд. Регулирование нагрузки применяется, если превышено число транзакций в течение нескольких 10-секундных периодов.

При достижении этого значения в течение первых нескольких секунд последующие транзакции блокируются до истечения десятисекундного перерыва. При этом вы получите сообщение об ошибке «429 Too many requests (Слишком много запросов)».

Если FedEx получит 1400 запросов в первые 2 секунды, в течение следующих 8 секунд все последующие транзакции будут блокироваться и вы получите сообщение об ошибке «429 Too many requests — We have received too many requests in a short duration. Please wait a while to try again» (429 Слишком много запросов — получено слишком много запросов за короткий промежуток времени. Подождите и повторите попытку).

По истечении 10 секунд ограничения нагрузки будут сняты и подсчет транзакций для следующих 10 секунд начнется заново.

Пороговые значения

Чтобы обеспечить устойчивость процесса авторизации API FedEx, пороговые значения действуют на уровне IP-адресов. Этот метод можно применять только в сочетании с услугой создания маркеров Auth. Используются пороговые значения двух типов:

1. пакетное пороговое значение — 3 обращения в секунду, повторяющиеся в течение 5 секунд;
2. среднее пороговое значение — 1 обращение в секунду, повторяющееся в течение 2 минут.

• Если общедоступный IP-адрес нарушает одно из указанных ограничений, он получает блокировку на 10 минут: все запросы, отправляемые в течение этого 10-минутного периода, получат в ответ код «403 Forbidden» (Доступ запрещен).
• Если пользователь API продолжает превышать указанные ограничения в течение штрафного периода, блокировка будет продлена. Чтобы добиться завершения штрафного периода, пользователю API достаточно не нарушать установленные лимиты в течение следующих 10 минут.
• Метод пороговых значений действует на уровне общедоступных IP-адресов пользователя. Если в рамках одного общедоступного IP-адреса установлено до 10 экземпляров виртуальных машин, при подсчете превышения порогового значения будут учитываться все обращения с этого IP-адреса.

Управление трафиком

Все три метода используются для управления трафиком на различных уровнях.

• Квоты, применяемые на уровне организации: учитывается общий трафик всех API в организации.

• Квоты, применяемые на уровне проекта: учитывается общий трафик одной возможности API в проекте.

• Ограничения частоты запросов, применяемые на уровне проекта: учитывается общий трафик всех API проекта.

• Пороговые значения применяются на уровне IP-адресов.

Примечание. FedEx может настраивать все перечисленные методы регулирования нагрузки, чтобы избежать ненадлежащего использования, перегрузок и злоупотреблений. FedEx оставляет за собой право менять значения ограничений без предварительного уведомления с целью обеспечить всем потребителям API равноправный доступ к информационным ресурсам FedEx и их эффективное распределение.

Ответы на часто задаваемые вопросы

При подсчете превышения квоты учитываются все транзакции API организации из разных проектов?
Подсчет превышения квоты осуществляется на уровне организации. В рамках одной организации может осуществляться несколько проектов, для каждого из которых может использоваться несколько API. При подсчете превышения дневной квоты учитываются общая сумма запросов всех API любых проектов в рамках одной организации.

Если для превышения квоты и частоты запросов действует один и тот же код ошибки 429, как понять, какое именно ограничение было нарушено?
Чтобы выяснить, какое именно ограничение нарушено, прочитайте сообщение об ошибке.

Как устранить проблему с нарушением порогового значения?
Маркер OAuth действителен в течение часа. Рекомендуется использовать его в течение всего часа и отправить запрос на получение нового только по истечении срока действия старого.

Как выглядит превышение порогового значения?
Периоды наблюдения для пакетного и среднего порогового значения — 5 секунд и 2 минуты соответственно. Если со стороны IP-адреса происходит превышение допустимой частоты запросов в течение этих периодов, для него начинает действовать штрафной период.

Пример. Если в течение 2 секунд с одного IP-адреса отправлено 3 обращения, но после этого частота обращений падает, нарушения нет. Однако если с одного и того же IP-адреса отправляются по 3 обращения в секунду в течение 5 секунд, а затем 15 обращений в течение 5 секунд, это считается превышением пакетного порогового значения (14 обращений за 5 секунд).