Integration best practice

This document presents the best practice to reliably integrate Media Gateway in your app. Before reading this document, follow the Media Gateway quickstart to understand the basic process of using Media Gateway.

The Agora server limits the call rate of the Media Gateway API, and returns the 429 (Too Many Requests) status code when the limit rate is exceeded. If you have higher call rate requirements, please contact Agora technical support.

API	Calling rate limit per project
Create	50 per second.
Delete	50 per second.
Query	100 per second.
Update	50 per second.

The limitation for concurrent streams is the following:

• 10 for streams with video transcoding
• 50 for streams without transcoding.

For higher quotas, please contact Agora technical support.

To ensure high availability of streaming services, and to avoid outages caused by regional network failures, Agora provides alternate domain names. Implement the following best practice to switch to an alternate domain name:

1. Based on the geographical location of your source stream, use the primary domain name from the following table:

   Geographical area	Primary domain name	Alternate primary domain name	Secondary domain name
   North America	rtls-ingress-prod-na.agoramdn.com	na.rtmpg.rtelink.com	na-backup.rtmpg.rtelink.com
   Europe	rtls-ingress-prod-eu.agoramdn.com	eu.rtmpg.rtelink.com	eu-backup.rtmpg.rtelink.com
   Asia excluding Mainland China	rtls-ingress-prod-ap.agoramdn.com	ap.rtmpg.rtelink.com	ap-backup.rtmpg.rtelink.com
   Chinese mainland	rtls-ingress-prod-cn.agoramdn.com	none	rtls-ingress-prod-backup-cn.agoramdn.com

2. If the request using the primary domain name fails, use the same domain to try again.

3. If the attempt still fails again, try the alternate domain name.

Implement the following best practice:

To ensure high availability of REST services, Agora enables you to switch domain names when you experience service outage due to regional network failures. Take the following steps to set up and switch your domain name:

1. Set the primary domain name based on the location of your service server:

   • If the DNS address of the service server is located in a country or region other than mainland China, set the primary domain name to api.agora.io.
   • If the DNS address of the service server is in mainland China, set the primary domain name to api.sd-rtn.com.

2. If your attempt to initiate a RESTful API request using the primary domain fails, set up your retry strategy as follows:

   1. Primary domain retry: Retry using the same primary domain name.

   2. Alternate domain retry:

      • If the current primary domain name is api.sd-rtn.com, use api.agora.io as the alternate domain name.
      • If the current primary domain name is api.agora.io, use api.sd-rtn.com as the alternate domain name.

   3. Adjacent domain retry: If alternate domain retry fails, retry using the domain name adjacent to the current region.

      For example, suppose your business server is located in Europe. You set the primary domain name to api.agora.io, and the business server resolves the primary domain name to Germany. Germany is located in central Europe (api-eu-central-1.agora.io). The domain name table shows that the adjacent area is West Europe. Use the api-eu-west-1.agora.io or api-eu-west-1.sd-rtn.com domain name to retry.

Take the following precautions when setting up your retry strategy:

• To avoid exceeding the QPS limit with retry requests, best practice is to use a back-off strategy. For example, wait 1 second before you retry for the first time, wait 3 seconds before retrying the second time, and wait 6 seconds before retry a third time.

• If the request fails because of a network problem rather than a DNS domain name resolution problem, skip alternate domain retry and proceed to adjacent domain retry.

• Before switching to the region domain name, ensure that the REST services you wish to use, for example, cloud recording or channel management, are deployed in that region.

The following table shows the primary and region domain names for various regions.

Primary domain name	Region domain name	Region
api.sd-rtn.com	api-us-west-1.sd-rtn.com	Western United States
	api-us-east-1.sd-rtn.com	Eastern United States
	api-ap-southeast-1.sd-rtn.com	Southeast Asia Pacific
	api-ap-northeast-1.sd-rtn.com	Northeast Asia Pacific
	api-eu-west-1.sd-rtn.com	Western Europe
	api-eu-central-1.sd-rtn.com	Central Europe
	api-cn-east-1.sd-rtn.com	East China
	api-cn-north-1.sd-rtn.com	North China
api.agora.io	api-us-west-1.agora.io	Western United States
	api-us-east-1.agora.io	Eastern United States
	api-ap-southeast-1.agora.io	Southeast Asia Pacific
	api-ap-northeast-1.agora.io	Northeast Asia Pacific
	api-eu-west-1.agora.io	Western Europe
	api-eu-central-1.agora.io	Central Europe
	api-cn-east-1.agora.io	East China
	api-cn-north-1.agora.io	North China

Refer to the following checklist to quickly confirm if each integration requirement for ensuring the connectivity and reliability of the Media Gateway service has been met.

#	Importance	Check
1	required	The Media Gateway service has been enabled for your App ID.
2	required	The API call rate is below the maximum limit. See API Call Limits for details.
3	required	The number of concurrent tasks in a project is less than 50. For details, see the maximum number of concurrent tasks.
4	required	The region is set to the geographical region of your media stream source. The region code is in lowercase.
5	optional	If calling the RESTful API fails, troubleshoot as follows: Use a back-off strategy. Check the error code. If the above troubleshooting methods do not solve your issue, contact Agora technical support with the X-Request-ID from the response header.
6	optional	If streaming fails using the RTMP/SRT protocol, please follow the steps below to troubleshoot: Ensure that the stream key has not expired. If you are using OBS streaming software, check that the frame loss rate is normal. If the above troubleshooting methods do not solve your issue, contact Agora technical support with your streaming domain name and streamKey values.
7	Optional	If the streaming service or REST service is unavailable due to network failure, follow the following solutions to troubleshoot: Try again using the current primary domain name. Change to the backup domain name and try again. If the above troubleshooting methods do not solve your issue, contact Agora technical support with your streaming domain name and streamKey values.