Skip to main content

API Gateway Rate Limiting

What is API Gateway rate limiting?​

API Gateway rate limiting is a protective mechanism that limits the number of API requests that can be sent to the system within a given time interval. This ensures service stability and availability for all partners.

Why is rate limiting needed?​

  • System stability: Protects backend systems from overload
  • Fair resource allocation: Ensures service availability for all partners
  • Protection: Prevents accidental or intentional overload

What does the limit apply to?​

The rate limit is enforced at the API Gateway level, which means it applies to all API calls:

  • EAM (qvik) initiation, query, cancellation
  • Payment Request operations
  • Payment API calls
  • Online Payment Page APIs
  • Other services

The API Gateway is shared among multiple partners, so the limit provides shared capacity.

API Gateway Error Codes​

The API Gateway can return different error codes in various situations. All error codes arrive in a uniform format:

{
  "errorCode": "ERROR_CODE",
  "errorId": "x-request-id value",
  "errorDescription": "Detailed error description"
}

403 - Forbidden Errors​

WAF_BLOCK​

The Web Application Firewall (WAF) blocked the request for security reasons.

{
  "errorCode": "WAF_BLOCK",
  "errorId": "request-id",
  "errorDescription": "Forbidden"
}

What to do? Check that the request does not contain potentially dangerous content. If you believe the blocking is incorrect, contact customer support.

INVALID_API_KEY​

The API key is invalid, incorrect, or missing from the request.

{
  "errorCode": "INVALID_API_KEY",
  "errorId": "request-id",
  "errorDescription": "Forbidden"
}

What to do?

  • Verify that your request includes the x-api-key header
  • Verify that you are using the correct API key
  • Verify that the API key is still valid

MISSING_AUTHENTICATION_TOKEN​

You called a non-existent API path (endpoint). AWS API Gateway returns this error when you try to access a path that is not defined, as it cannot perform authentication in such cases.

{
  "errorCode": "MISSING_AUTHENTICATION_TOKEN",
  "errorId": "request-id",
  "errorDescription": "Missing Authentication Token"
}

What to do? Check your API endpoint URL. Make sure that:

  • The full path is correct (e.g., not /v1/eam/initiate instead of /v1/eam/init)
  • There are no typos in the URL
  • You are using the correct environment (test/production)
  • The API version (e.g., /v1/) is correct

404 - Not Found​

RESOURCE_NOT_FOUND​

The requested resource or endpoint was not found.

{
  "errorCode": "RESOURCE_NOT_FOUND",
  "errorId": "request-id",
  "errorDescription": "Missing Authentication Token"
}

What to do? Check the endpoint URL and make sure you are using the correct API path.

429 - Too Many Requests​

USAGE_PLAN_THROTTLING_LIMIT_EXCEEDED​

You have exceeded the limit for the number of requests per second (throttling).

{
  "errorCode": "USAGE_PLAN_THROTTLING_LIMIT_EXCEEDED",
  "errorId": "request-id",
  "errorDescription": "Too Many Requests"
}

What to do? Wait a short time, then retry the request with exponential backoff (see below).

USAGE_PLAN_QUOTA_EXCEEDED​

You have exceeded the usage plan quota (e.g., daily or monthly limit).

{
  "errorCode": "USAGE_PLAN_QUOTA_EXCEEDED",
  "errorId": "request-id",
  "errorDescription": "Rate exceeded"
}

What to do? Wait a short time, then retry the request. The quota will reset over time. Implement retry logic with exponential backoff (see below).

How to recognize rate limit exceeded?​

When you exceed the rate limit, you will receive one of the above 429 error codes (USAGE_PLAN_THROTTLING_LIMIT_EXCEEDED or USAGE_PLAN_QUOTA_EXCEEDED).

What to do when rate limit is exceeded?​

1. Retry the request later​

When you receive an HTTP 429 error, do not give up immediately. The request can be successfully executed later.

2. Implement retry logic with exponential backoff​

The recommended solution is the exponential backoff strategy:

1st attempt: immediate
2nd attempt: wait 1 second
3rd attempt: wait 2 seconds
4th attempt: wait 4 seconds
5th attempt: wait 8 seconds
... and so on

Best Practice recommendations​

1. Don't send parallel requests unnecessarily​

If possible, group or batch operations instead of sending many small requests at once.

2. Implement proper error handling​

Every API call should have error handling capable of handling the 429 status code.

Frequently Asked Questions​

What is the exact rate limit?​

The current overall limit is 20 TPS, which is shared among multiple partners and is regularly reviewed.

What happens if I continuously exceed the limit?​

The system automatically rejects requests with HTTP 429 error. In the long term, we recommend reviewing and optimizing your integration.

How can I avoid rate limit problems?​

  • Implement retry logic with exponential backoff
  • Avoid excessive use of parallel requests
  • Use caching where possible
  • Design API calls to be evenly distributed over time