True Random Number Service

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
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-2017 RANDOM.ORG
Terms and Conditions
About Us