Errors
This section provides information on the various HTTP status codes and corresponding error definitions that may be encountered while interacting with the API.
HTTP Responses
The HTTP response codes play a crucial role in determining the success of an API request. In case of failure, these codes provide valuable insights into the nature of the error and whether a retry is advisable.
| Code | Definition | Description |
|---|---|---|
| 200 | OK | The request was successful. |
| 201 | Created | The request has been successfully processed and a new resource has been created. |
| 400 | Bad Request | Client provided invalid arguments. Please review the response for error details. Retrying with the same arguments will not work. |
| 401 | Unauthorized | Client did not supply credentials or did not provide the correct credentials. See Authentication. |
| 403 | Forbidden | Client is not authorized to view the requested resource. |
| 404 | Not Found | The requested resource was not found. |
| 408 | Request Timeout | The request took too long to process. Please try again. |
| 409 | Conflict | The request could not be completed due to a conflict with the current state of the resource. |
| 429 | Too Many Requests | The client is making requests too frequently. Wait a moment before making further requests and make them at a reduced rate. See Limits for more detail. |
| 500 | Internal Server Error | Unknown error occurred while processing request. |
Detailed errors responses
Below is a list of specific error messages and guidance for resolving them. While the messages are designed to be informative, this section provides additional context for troubleshooting.
Authentification
Authentication errors indicate that the API is unable to identify the person trying to access the services. If the API cannot determine who is using the service, it will not be able to infer the associated permissions.
Header X-API-Token missing
Example Response:
Explanation:
Access to the lottery endpoints requires token-based authentication. When making a request to the API, you must ensure that the X-API-Token header is present and contains the value of the token you created.
Refer to the Authentication section for more details.
Example Response:
Explanation:
The token provided in the X-API-Token header does not exist. Please verify that you are using your token correctly. You can delete and recreate it if you have forgotten its value.
Info
We encourage users to store their token in a secure place.
Header Authorized missing
Example Response:
Explanation:
Access to the account management endpoints requires JWT token authentication. When making a request to the API, you must ensure that the Authorization header is present.
Refer to the Authentication section for more details.
Invalid JWT token
Example Response:
Explanation:
If you encounter this issue, it is likely because you are trying to manage your profile without using the website. Currently, no documentation is available to guide you in this use case. Please feel free to contact us for more information.
Authorization
License required
Example Response:
{
"code": 403,
"error": "Forbidden",
"message": "Your account does not have the required license. Please purchase a license."
}
Explanation:
You are trying to access a resource that requires a specific license which you do not have or no longer possess. You need to acquire the appropriate license to access it.
Info
Currently, the error message is generic. Improving the error message is planned for a future version.
Profile
Your account has been disabled.
Example Response:
Explanation:
API access is disabled manually and only when an account appears to be making requests it should not be making (sabotage, attempts to find security vulnerabilities, or any violation of our terms of use).
If you encounter this issue and believe it to be unjustified, we encourage you to contact us to attempt to reactivate your account : contact@lotteryresultsapi.com
Quota exceeds
Example Response:
{
"code": 403,
"error": "Forbidden",
"message": "You have exceeded your licence quota for this month. Wait next month or upgrade your license."
}
Explanation:
For reasons of fair use and platform stability, we apply quotas based on the license you hold. You can either wait for the reset at the beginning of the next month, or you can purchase a higher-tier license to increase your quota for this month and the months to come.
For more details on license quotas, refer to the limits section.
Info
Please note that executing requests that result in errors also consumes your quota. Make sure to follow best practices when using our API.
Profile token
Token not found
Example Response:
Invalid token id
Example Response:
{
"code": 401,
"error": "Bad Request",
"message": "Invalid request. The token 'id' field must not be empty."
}
Explanation:
The payload to create a new token requires a unique id to identify your token. This value is the minimum required to create a new token. Please refer to the token documentation for instructions on how to create a new token.
Token conflict
Example Response:
{
"code": 401,
"error": "Bad Request",
"message": "Token already exists with the provided identifier."
}
Explanation:
You have already created a token with the same identifier. You need to choose a new one, or remove and recreate the existing token with the same identifier to reset the API token.
Maximum token count reach
Example Response:
{
"code": 401,
"error": "Bad Request",
"message": "You have reach the maximum of authorized token."
}
Explanation:
You have reached your maximum number of allowed identification tokens. This limit is enforced to prevent abuse. However, if you have specific needs, please feel free to contact us so we can better understand your requirements and explore the possibility of adjusting the token quota management: contact@lotteryresultsapi.com
Lotteries
Lottery not found
Example Response:
Explanation:
The tag used in the API does not correspond to any available lottery. Check the list of available lotteries ici or via the GET https://api.lotteryresultsapi.com/lottery endpoint.
Invalid lottery tag
Example Response:
{
"code": 401,
"error": "Bad Request",
"message": "Invalid request. The lottery 'tag' field must not be empty."
}
Explanation:
You have provided an incorrect lottery tag value. Check the list of available lotteries ici or via the GET https://api.lotteryresultsapi.com/lottery endpoint.
Lottery draws
Draw not found
Example Response:
Explanation:
Check if the provided date is correct and valid according to the lottery's draw schedule.
Invalid draw date format
Example Response:
{
"code": 401,
"error": "Bad Request",
"message": "Invalid 'drawDate' value. Expected 'YYYY-MM-DD' format."
}
Explanation:
The draw date format is incorrect. Please ensure the format is correct. The date should consist of the year in four digits, followed by the month and day, separated by hyphens.
Draw date is too old
Example Response:
{
"code": 401,
"error": "Bad Request",
"message": "Invalid request. The draw date cannot be before 1800-01-01."
}
Explanation:
If you try to access a draw earlier than 1800, this indicates that your use case for the API is not appropriate. Why 1800? Most modern regular lotteries have existed only since the 1950s.
Warning
If you attempt to trigger this error, your monthly quota will be affected by this request. Think twice before doing so :)
Others errors
Generic internal server error
Example Response:
{
"code": 500,
"error": "Internal Server Error",
"message": "Unexpected error occurred. An administrator has been notified of this error so they can fix it."
}
Explanation:
This is the generic error displayed when specific server-side issues occur. The details of the errors are intentionally hidden from the user, as they are too complex to summarize in a short error message. These errors should not occur, and an administrator is notified when they do. We apologize in advance if you encounter this error.
Rate limit error
Example Response:
Explanation:
For more details on rate limits, refer to the limits section.