Advisory: We only operate services from the RANDOM.ORG domain. Other sites that claim to be operated by us are impostors. If in doubt, contact us.
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.
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. |
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
}
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
}
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
}
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.
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
}
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
}
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
}