Skip to main content

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.

API call limits

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.

APICalling rate limit per project
Create50 per second.
Delete50 per second.
Query100 per second.
Update50 per second.

Maximum number of concurrent tasks

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.

Ensure high availability of streaming services

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 areaPrimary domain nameAlternate primary domain nameSecondary domain name
    North Americartls-ingress-prod-na.agoramdn.comna.rtmpg.rtelink.comna-backup.rtmpg.rtelink.com
    Europertls-ingress-prod-eu.agoramdn.comeu.rtmpg.rtelink.comeu-backup.rtmpg.rtelink.com
    Asia excluding Mainland Chinartls-ingress-prod-ap.agoramdn.comap.rtmpg.rtelink.comap-backup.rtmpg.rtelink.com
    Chinese mainlandrtls-ingress-prod-cn.agoramdn.comnonertls-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.

Ensure high availability of REST services

Implement the following best practice:

Switch the domain name

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.

Precautions

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.

Domain name table

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

Primary domain nameRegion domain nameRegion
api.sd-rtn.comapi-us-west-1.sd-rtn.comWestern United States
api-us-east-1.sd-rtn.comEastern United States
api-ap-southeast-1.sd-rtn.comSoutheast Asia Pacific
api-ap-northeast-1.sd-rtn.comNortheast Asia Pacific
api-eu-west-1.sd-rtn.comWestern Europe
api-eu-central-1.sd-rtn.comCentral Europe
api-cn-east-1.sd-rtn.comEast China
api-cn-north-1.sd-rtn.comNorth China
api.agora.ioapi-us-west-1.agora.ioWestern United States
api-us-east-1.agora.ioEastern United States
api-ap-southeast-1.agora.ioSoutheast Asia Pacific
api-ap-northeast-1.agora.ioNortheast Asia Pacific
api-eu-west-1.agora.ioWestern Europe
api-eu-central-1.agora.ioCentral Europe
api-cn-east-1.agora.ioEast China
api-cn-north-1.agora.ioNorth China

Troubleshooting checklist

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.

#ImportanceCheck
1requiredThe Media Gateway service has been enabled for your App ID.
2requiredThe API call rate is below the maximum limit. See API Call Limits for details.
3requiredThe number of concurrent tasks in a project is less than 50. For details, see the maximum number of concurrent tasks.
4required
  • The region is set to the geographical region of your media stream source.
  • The region code is in lowercase.
5optionalIf calling the RESTful API fails, troubleshoot as follows:
If the above troubleshooting methods do not solve your issue, contact Agora technical support with the X-Request-ID from the response header.
6optionalIf 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.
7OptionalIf 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.
vundefined