Error Codes and Messages (Release 3)

Introduction

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 defined:

Code Message Data Types
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
305 The value you specified for parameter '%s' does not match the expected value of '%s' string, string
306 Use of parameter '%s' requires use of parameter '%s' string, string
307 The language '%s' you requested is not supported for this operation string
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
406 You already have %s API keys and the maximum allowed with your account is %s integer, integer
420 The ticket you specified does not exist null
421 The ticket you specified exists but is not for the API key you specified null
422 The ticket you specified has already been used null
423 You already have %d singleton tickets for this API key and the maximum allowed is %d integer, integer
500 You are not subscribed to the %s string
501 You are already subscribed to the %s string
502 The credentials '%s' you specified are not valid or have expired string
503 Your prepaid account credit is negative; please top up and retry null
504 The delegate '%s' you specified did not accept your delegation integer
505 You are not allowed to perform this operation null
506 You need %s prepaid account credit for this operation, but you only have %s float, float
507 This service does not expire null
508 This service cannot be delegated null
509 Your subscription to this service does not allow the authentication mode you specified null
600 You requested %d winners to be picked, but you only supplied %d eligible entries integer, integer
601 The value you specified for parameter '%s' contains %d blank entries string, integer
602 You requested identical entries not be permitted, but you supplied entries with multiple occurrences null
603 This operation is not permitted null
604 This operation has already been completed null
605 This operation has not yet been completed null
606 Too few unpicked values remain to perform this operation. null
700 No connection to the payment service provider could be established null
701 The payment service provider is down null
702 The payment was declined by the payment service provider 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
}