True Random Number Service

Note: There is a newer version of this API available.

JSON-RPC API – Release 1 – Error Codes

This page lists all the errors that a client can encounter from the API. Some are related to JSON-RPC and others to the RANDOM.ORG API.

JSON-RPC Errors

[+]

The API implements the error codes listed in the JSON-RPC 2.0 Specification:

code message meaning
-32700 Parse error Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
-32600 Invalid Request The JSON sent is not a valid Request object.
-32601 Method not found The method does not exist / is not available.
-32602 Invalid params Invalid method parameter(s).
-32603 Internal error Internal JSON-RPC error.
-32000 to -32099 Server error Reserved for implementation-defined server-errors.

Example 1

The following invokes a method that does not exist:

{
    "jsonrpc": "2.0",
    "method": "fooBar",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 10,
        "min": 1,
        "max": 10,
        "replacement": true,
        "base": 10
    },
    "id": 18197
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32601,
        "message": "Method not found",
        "data": null
    },
    "id": 18197
}

Example 2

The following is missing the jsonrpc version identifier:

{
    "method": "generateIntegers",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 10,
        "min": 1,
        "max": 10,
        "replacement": true,
        "base": 10
    },
    "id": 18197
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32600,
        "message": "Invalid Request",
        "data": null
    },
    "id": 18197
}

Example 3

The following has the wrong name for the characters parameter:

{
    "jsonrpc": "2.0",
    "method": "generateStrings",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 10,
        "length": 4,
        "chars": "abcdefghijklmnopqrstuvwxyz",
        "replacement": true
    },
    "id": 18197
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Invalid params",
        "data": null
    },
    "id": 18197
}

RANDOM.ORG Errors

[+]

The following RANDOM.ORG-specific errors are also defined:

code message data
100 Method not (yet) implemented null
101 Service offline; please try again later null
200 Parameter '%s' is malformed string
201 Parameter '%s' has illegal value string
202 Parameter '%s' is out of range; allowable values are [%d,%d] string, integer, integer
203 Parameter '%s' has length %d, which is too long; maximum length is %d string, integer, integer
204 Parameter '%s' has length %d, which is too short; minimum length is %d string, integer, integer
300 Parameter '%s' must be less than parameter '%s' string, string
301 You requested %d values without replacement but the domain you specified only contains %d integer, integer
302 The value you specified for parameter '%s' has already been taken string
303 The resource identified by '%s' was not found string
304 The resulting data's size would be %d, which exceeds the maximum of %d integer, integer
400 The API key you specified does not exist null
401 The API key you specified is not running null
402 The operation requires %d requests, but the API key only has %d left integer, integer
403 The operation requires %d bits, but the API key only has %d left integer, integer
404 The API key you specified is not valid for the method you requested null
405 The API key you specified is not valid for the version of the API you are invoking null
500 You are not subscribed to %s string
501 The credentials '%s' you specified are not valid or have expired string
502 Your prepaid account credit is negative; please top up and retry null
32000 Unknown error: %s string

The three columns in the table corresponds to the three fields in the JSON-RPC error object. The code field is intended to be machine-readable. The message field is a human-readable string intended for display to a user or for inclusion in a log file. The data field contains the values of the positional parameters from the message string in case that the client wishes to customize the error message.

Example 1

The following requests integers using an API key that doesn't exist:

{
    "jsonrpc": "2.0",
    "method": "generateIntegers",
    "params": {
        "apiKey": "ffffffff-ffff-ffff-ffff-ffffffffffff",
        "n": 10,
        "min": 1,
        "max": 10,
        "replacement": true,
        "base": 10
    },
    "id": 1247
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "error": {
        "code": 400,
        "message": "The API key you specified does not exist",
        "data": null
    },
    "id": 1247
}

Example 2

The following passes a string as the number of integers to generate:

{
    "jsonrpc": "2.0",
    "method": "generateIntegers",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": "xyz",
        "min": 1,
        "max": 10,
        "replacement": true,
        "base": 10
    },
    "id": 18197
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "error": {
        "code": 200,
        "message": "Parameter 'n' is malformed",
        "data": [
            "n"
        ]
    },
    "id": 18197
}

Example 3

The following requests more unique integers than there are in the specified range:

{
    "jsonrpc": "2.0",
    "method": "generateIntegers",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 12,
        "min": 1,
        "max": 10,
        "replacement": false,
        "base": 10
    },
    "id": 238
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "error": {
        "code": 301,
        "message": "You requested 12 values without replacement but the domain you specified only contains 10",
        "data": [
            12,
            10
        ]
    },
    "id": 238
}

© 1998-2019 RANDOM.ORG
Valid XHTML 1.0 Transitional | Valid CSS
Web Design by TSDA