Editar

Compartilhar via

Handling errors in CloudScript

  • Artigo

This tutorial describes how to recognize and handle errors within your CloudScript handlers.

Identifying

The first step is identifying the error. While every uncaught error is logged and available from the response to the caller (client), you can catch the error early by using a try/catch block.

Consider the following CloudScript snippet that produces and catches the error.

"use strict";

handlers.GenerateError = () => {
    try {
        server.GetPlayerStatistics({
            PlayFabId : "non-existing-player-id"
        });
    } catch (ex) {
        let error = ex.apiErrorInfo.apiError.error; // In this case - "InvalidParams"
        let errorCode = ex.apiErrorInfo.apiError.errorCode; // In this case : 1000
    }
}

Notice how the error codes were extracted within the catch block? Consult our Global API method error codes documentation for a complete list of errors.

Note

The error code on its own is sufficient to identify the error.

Logging

Any unhandled error is added to the response, allowing the client to process the problem.

At the same time, it creates a CloudScript error entry and adds it to the total statistics available on your CloudScript dashboard.

Game Manager - CloudScript Dashboard showing a graph of API errors

To force-log the exception in the form of a JSON string, use error logging via the log object.

"use strict";

handlers.GenerateError = () => {
    try {
        server.GetPlayerStatistics({
            PlayFabId : "non-existing-player-id"
        });
    } catch (ex) {
        log.error(ex);
    }
}

Finally, you can write title/player events for later processing through analytics.

"use strict";

handlers.GenerateError = () => {
    try {
        server.GetPlayerStatistics({
            PlayFabId : "non-existing-player-id"
        });
    } catch (ex) {
        server.WriteTitleEvent({
            EventName : 'cs_error',
            Body : ex
        });
    }
}

Recovery

It's not always possible to recover from errors. Issues such as InvalidArguments leave you with no option but to report the problem back to the player.

There are a subset of errors where a retry strategy can be applied. Retry-able error types are described in the Global API Method Error Codes.

We ask that you make sure you meet the following requirements when applying a retry strategy:

  • With each retry, the delay between retries should increase exponentially. This increases your chances for a successful call, and prevents your game from spamming the PlayFab server (which will result in more rejected calls).

  • You should apply this retry strategy selectively, only using it for those codes that are worth retrying.

CloudScript timeout error

The execution time of CloudScript API calls is limited to 4 seconds.

If the execution time exceeds 4 seconds, an InternalServerError is raised and the PlayStream Event writes a Logs object similar to the following:

    "Logs":[
        {
        "Level":"Error",
        "Message":"PlayFab API request failure",
        "Data":{
            "request":{
                "PlayFabId":"9437A5ADDAE3012D"
            },
            "error":"Timeout",
            "api":"/Server/GetPlayerSegments"
        }
        }
    ]

If you encounter this error, you can: