Error Handling

The API uses standard HTTP status codes to indicate whether a request succeeded or failed.

2xx indicates a successful request
4xx indicates a client-side problem such as invalid input, missing authentication, or an action that cannot be performed
5xx indicates an unexpected server-side failure

Error categories

Errors generally fall into two groups:

Client errors: the request must be corrected before retrying
Server errors: the request may be valid, but the API failed while handling it

Client errors

Client errors return a 4xx status code. These usually mean one of the following:

The request body or query parameters are invalid
Authentication is missing or invalid
The requested resource does not exist
The requested action is not allowed in the current state
Your account does not have enough balance to perform the action
You have exceeded the rate limit

For client errors, correct the request before retrying.

Server errors

Server errors return a 5xx status code. These indicate that the API failed while processing an otherwise valid request. When you receive a server error:

Treat the result as indeterminate
Retry only when it is safe for your use case
Capture the x-request-id response header
Include the request ID if you contact support

Error response format

Error responses are returned as JSON. In most cases, you can expect at least a stable code field and a human-readable message field. The examples below show a typical authentication error, a validation error, and a server-side failure:

{
  "code": "request_errors",
  "message": "Request error occurred.",
  "data": {
    "errors": [
      {
        "code": "invalid_type",
        "message": "Expected string, received number",
        "path": ["label"]
      }
    ]
  }
}

{
  "code": "not_authorized",
  "message": "Not authorized to perform this action."
}

{
  "code": "server_error",
  "message": "Internal server error occurred.",
  "requestId": "6f3b3d9f-4c47-4fd7-8a53-0d7f0f4e6abc"
}

Depending on the failure type, the response may include additional details:

Validation errors can include a structured data.errors array with field-level information such as the invalid path, the validation code, and a specific message.
Malformed JSON may return a simpler 400 response with only code and message.
Server errors can include a requestId field in the response body so you can correlate the failure with logs or share it with support.

Common status codes

HTTP Status Code	Meaning
`400 Bad Request`	The request could not be processed because parameters, query values, or the JSON body were invalid.
`401 Unauthorized`	The API key is missing, invalid, disabled, or not authorized for the request.
`402 Payment Required`	The action requires more balance than is currently available on the account.
`404 Not Found`	The requested resource could not be found.
`406 Not Acceptable`	The requested action is not compatible with the target resource or selected duration.
`409 Conflict`	The request conflicts with existing data, such as a username or MAC address that already exists.
`429 Too Many Requests`	The rate limit has been exceeded. Retry with backoff.
`500 Internal Server Error`	An unexpected server-side error occurred.

Common error codes

The API may return error codes such as:

request_errors
not_authorized
insufficient_balance
member_not_found
api_key_not_found
api_key_disabled
username_already_exist
macaddress_already_exist
line_not_authorized
line_not_found
unavailable_duration
rate_limit
server_error

Handle the code field programmatically when you need stable application logic, and use the message field for human-readable debugging information.

Getting Started

API Overview

Error categories

Client errors

Server errors

Error response format

Common status codes

Common error codes

​Error categories

​Client errors

​Server errors

​Error response format

​Common status codes

​Common error codes

Error categories

Client errors

Server errors

Error response format

Common status codes

Common error codes