Common errors

This page lists the error and status codes you may encounter when using the Real-Time STT RESTful APIs. In case of other errors, contact Agora technical support.

When calling Real-Time STT RESTful APIs, you may receive the following HTTP status codes:

• 200 for a successful request.
• Not 200 for a failed request. In this case, check the message, code, and reason fields in the response body to figure out what has happened. The reason field might be absent.

When a request fails, you may receive the following response:

• Only message:

  
  

  _5

  # 401 Unauthorized

  _5

  # only message

  _5

  {

  _5

  "message": "Invalid authentication credentials"

  _5

  }

  
  

• Only code and reason:

  
  

  _6

  # 400 Bad Request

  _6

  # only code and reason

  _6

  {

  _6

  "code": 2,

  _6

  "reason": "Acquire: invalid resourceExpiredHour value!"

  _6

  }

  
  

Code	Description
200	The request is successful. To call acquire, record tokenName. To call start, record taskId and map it to tokenName.
201	The service is already running. Do not repeat the start request with the same tokenName.
206	No host in the channel sent a stream during the transcribing process.
400	The server cannot process the request due to malformed request syntax, or the Real-Time STT service is not enabled.
401	Unauthorized (incorrect Customer ID/Customer Secret).
404	The requested resource could not be found.
409	The task has already been started.
500	Internal server error.
504	Internal communication error.

• "the product name does not match with builderToken": The acquired buildToken has an issue. Call acquire again.
• "resourceId reaches out the limited time interval!": The buildToken expired after the 5-minute validity period. Make sure to use tokenName to start the service within 5 minutes after calling acquire. When the task has been created successfully, save the tokenName, since it will be used to call query, update, and stop.
• "invalid_appid!": The Real-Time STT service is not enabled for your app. Enable it in the Console or send a request to Agora technical support.
• "body schema check fail, ...": The start or update body is wrong. "..." describes the reason of failure. Always caused by parameter mismatch or exceeding the range. Recheck the request body.
• "The taskId does not match with builderToken.": Check why taskId and tokenName do not match.
• "The task is not found": The task has been terminated.
• "The task has been started, current status is STARTED, taskId is ...": The task has been started. Record taskId and map it to tokenName.

• 1: Internal server error when calling start. Contact Agora technical support if you need more support.
• 2: Invalid parameter. Possible reasons:
  • Wrong data type.
  • Wrong spelling. All parameters are case sensitive.
  • Parameter value is out of range.
  • Mandatory parameter is missing.
• 6: Internal server error when calling start. Contact Agora technical support if you need more support.
• 20: Caused by processing timeout. Retry the same call with the back-off strategy, after 3 and 6 seconds.
• 23: Internal server error when calling start. Contact Agora technical support if you need more support.
• 49: Caused by repeated start requests with the same tokenName or repeated stop requests with the same tokenName and taskId.
• 53: taskid and buildtoken do not match.
• 62: If you receive this error when calling acquire, the Real-Time STT service is not enabled for your App ID. Enable it in the Console or contact Agora technical support. If you receive this error when calling start, it means the service is not started due to a network issue.
• 404: The task has been terminated when calling query or stop.
• 501: Internal server error when calling start. Contact Agora technical support if you need more support.
• 502: Internal server error when calling start. Contact Agora technical support if you need more support.
• 504: Internal server error when calling start. Contact Agora technical support if you need more support.
• 1001: Failed to parse tokenName. Call acquire to get a new tokenName.
• 1003: The App ID or taskId does not match tokenName. Ensure that the App ID or taskId matches tokenName in each Real-Time STT task.

• The resourceId and tokenName parameters are the same. In some cases, builderToken also means tokenName.
• Contact Agora technical support if you encounter an error not mentioned in this documentation.