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
}