RingCentral API Error Codes

The API uses specific error codes to make error processing for client applications more simple and effective. The body of the HTTP response should be always logged and analyzed. Sometimes it is impossible to understand the cause of the issue by only HTTP status code. The error code from the response body should be also taken into consideration.

Client apps should rely on the errorCode and, in some cases, on additional fields like parameterName, not on the error message (because it may change in the next versions of the API or be localized). Response body with error message can contain several error messages and has the following structure:

{
    "errors": [
    {
        "errorCode": "ABC-123",    
        "message": "Error message",
        "additionalInfo": "value",  // additional attribute for this error, e.g "parameterName": "extensionId"
    },
    {
        "errorCode": "XYZ-321",
        "message": "Second error message"
    }
    ]
}

The API reference lists some of the error codes that may be returned for a particular API operation.

Connectivity errors

There is always a possibility that a client application is not able to connect with RingCentral service due to the following reasons:

• HTTP connection timeout
• HTTP request timeout
• TLS handshake error

These situations are usually temporary. The application should use Exponential Backoff approach to retry.

General 5xx server errors

Clients may receive HTTP 5xx errors (typically, 500/502/503/504) when a server cannot handle a request due to some server-side issue. Such situations are usually temporary and applications may retry as suggested in Exponential Backoff. If retries don't help in your case please contact RingCentral developers support.

Authentication related errors

Since the RingCentral API uses OAuth 2.0 for authorization, the server behavior is mostly governed by the OAuth specification (RFC 6749 and RFC 6750).

• Regardless of the number of threads that send API requests to the server, the application should perform OAuth authentication in a single thread, then store and share tokens to be used in all regular API requests. Backend servers enforce some quotas for the number of authorization requests and number of active application sessions. If the quota is exceeded at any given time, the server starts to return HTTP 429 on authorization requests.
• Applications must avoid frequent authentication attempts under the same user credentials. In order to extend the session after access token expiration, the token refreshment flow should be used if allowed
• Applications should store expires_in and refresh_token_expires_in values along with access/refresh tokens and their issue time. This value is to be used to pre-check if the token is expired or about to expire before sending regular API requests in order to refresh tokens proactively. It is strongly recommended to avoid refreshing tokens based on HTTP 401 errors returned by the server: this just doubles the number of requests required to get a new access token.
• According to the OAuth 2.0 standard, some standard OAuth error codes are returned in the response complemented with RingCentral-specific error codes.

OAuth authorization errors

For 3-legged OAuth flows, in some cases, HTTP 400 may be returned on the /restapi/oauth/authorize call. This can happen when the client provides an invalid redirect URI in the request. See RFC 6749 for details.

OAuth token errors

As a general rule, if a request to the /restapi/oauth/token API for access token fails client must NOT send other API requests until resolved. It has to be properly orchestrated if a client uses multiple threads that share the same tokens to send regular API requests.

• HTTP 400 – do not repeat request; if possible inform the user about the failure and prompt for new credentials
• HTTP 429, HTTP 503 – retry in an indicated interval returned in the Retry-After header.
• HTTP 4xx, HTTP 5xx – do not repeat request, error in client or server code
• HTTP 400 – use cached credentials (if possible) to re-authenticate or prompt the user for new credentials.
• HTTP 408, HTTP 500, client timeout – repeat 3 times with 10 seconds intervals, then try re-request tokens using cached credentials (if possible), or prompt the user for new credentials (all dependent regular requests should be queued and wait for resolution)

OAuth revokation errors

If the request to the /restapi/OAuth/revoke API ends with an error, the client should ignore it and not retry.

Authentication/authorization error codes

Rate-limit related error codes

Notification subscription related error codes

General API error codes

Messaging API error codes

Exponential Backoff

The Exponential Backoff approach helps to avoid overwhelming backend servers with excessive request retries, making ongoing incidents more severe, and preventing clients from being penalized for making an excessive number of requests. The basic idea is that the client retries with exponentially increased intervals up to a certain threshold: if the server is down temporarily, it will not be overwhelmed with all the requests hitting it at the same time when it comes back up.

When the app experiences an error that is caused by a server issue and retries are allowed, the following strategy is recommended.

• Your app should have the following configuration options:
• Initial retry interval (e.g. 2 seconds)
• Maximum number of retries (e.g. 5)

• Optional maximum retry interval (e.g. 60 seconds)

• In case of an error that may be handled by retries:

• If a Retry-After header was provided in response, retry after the provided interval.
• Otherwise
  • The first retry should occur after the configured initial retry interval
  • The wait interval for each next retry should be calculated as 2 * previous-retry-interval
  • Repeat until the maximum number of retries is reached, OR
  • Once the maximum retry interval is reached, repeat with the last interval until the maximum number of retries

The example of exponential backoff retry intervals with 2 seconds / 8 retries configuration:

• 2 seconds
• 4 seconds
• 8 seconds
• 16 seconds
• 32 seconds
• 64 seconds
• 128 seconds
• 256 seconds

The example of exponential backoff retry intervals with 2 seconds / 50 retries / 60 seconds max configuration:

• 2 seconds
• 4 seconds
• 8 seconds
• 16 seconds
• 32 seconds
• 64 seconds
• 64 seconds
• 64 seconds
• ... (until 50 attempts reached)