We have a number of detailed error messages that handle a variety of situations. You don’t have to interact with these error messages if you don’t want to, but showing them to end users (or showing custom messages based on the responses) is helpful to diagnose issues or instruct end users.
The error messages are sent as a request response via JSON headers and look like this:
{"ERROR":"This is the error message"}If you wish to show a single custom message you should check if ERROR is found in the response and, if so, show your generic custom message. You can also check for specific error message responses (listed below) and show unique custom messages based on them.
List of Error Codes #
Due to security, this is not a complete list of errors the end user may experience. Some error messages are only logged on our end and are not sent. To allow for such errors but still send a message to the user, create a catch-all else statement that will display a generic message if no JSON message was received.
- Invalid license key (CODE: L3n7) [length of key is not correct]
- Invalid license key (CODE: C4r5) [invalid characters in key]
- Invalid license key (CODE: P477) [key does not match the correct pattern]
- Failed to activate key! [key was found but failed to activate, likely a connection error]
- User IP Error! [end user’s ip address is failing to send or not IP4 or IP6 format, likely a connection error]
- You’re sending keys too fast. Please try again later. [either the app or the end user has sent keys too quickly and been timed out]
Again, there may also be other error messages not provided for security reasons. We recommend using a generic catch-all else statement error message for instances where “valid” is “0” but none of these messages are found.
Invalid Key Code #
While an invalid key code is not necessarily considered an error message we will mention it here for completeness. An invalid key sends back this JSON header:
{"valid" : "0"}Typical reasons for a key returning as invalid are the key was not found, your API auth key was not sent with the key, the key is being used on an unauthorized domain (for domain locked keys), or the UUID of the current end user does not match the end user already assigned to the key (for UUID locked keys).
Developer Specific Error Codes #
If a key check fails due to misconfiguration of your code you might experience the below errors. You will typically find these errors during development testing and under normal circumstance the end user will not see these messages.
BatchKeys API Auth Key is required! (CODE:d3v3rr1)
This message indicates your key checking code does not include your API authorization key. Your API auth key can be found in your Dashboard. For security purposes, our API requires the unique authorization key to be included in every key check in the form of “auth” in the request headers.
We recommend following standard best practices and assign your API auth key to a variable inside an environmental variable or other local file, you should not hard code an API authorization key.
NOTE: While your API auth key is unique to you, it does not contain any personal identifiable information.
License key is required! (CODE:d3v3rr2)
This message indicates your license key checking code does not include the license key. To check a key it must be sent to our API in the form of “key” inside the request headers.
We recommend collecting the key from the end user using a form during activation. Save this information in a local file for future key checks, like on startup or a daily timed check.
Preventing End User Errors #
The easiest way to prevent user error is to help them input the key. The simplest way to do this is to add a placeholder to the input field that looks like a valid key. By showing them the proper format and location to input the key they will hopefully have no trouble.
Avoiding Rate Limit Errors #
To prevent misuse of our systems we have implemented sophisticated AI powered software that secures our website. One factor this software uses is API requests and server pings rate limits.
If your end user is receiving “You’re sending keys too fast. Please try again later. ” error messages they have hit a rate limit and are being timed out.
See our documentation on staying within rate limits to avoid this type of message.