Responses, Formats and Errors | Control-WebPanel Documentation

This page explains what the CWP API returns, how to tell success from failure, and how to deal with the most common errors.

Response format

Responses are JSON by default. The format is chosen per API key in API Manager (Format Request: JSON or XML), not per request.

A successful call returns "status":"OK":

{"status":"OK"}

Calls that return data add it in a field — usually msj, sometimes result or a function-specific name:

{"status":"OK","msj":[{"database":"john_shop","user":"","host":""}]}
{"status":"OK","result":"Conex Api OK"}
{"status":"OK","emailadmin":"admin@example.com"}

A failed call returns "status":"Error" and a message in msj, result or message:

{"status":"Error","msj":"key does not exist"}
{"status":"Error","result":"All data is required"}

Note: Always check the status field, not only the HTTP status code. Most errors are returned with HTTP 200. The name of the data/message field differs between functions — the examples on each function page show exactly which field to read.

Recommended handling

Parse the body as JSON. If it is not valid JSON, treat the call as failed (see Unexpected HTML below).
If status is "OK", read the data field documented for that function.
Otherwise read msj, result or message (whichever exists) as the error text and log it.
Before retrying an add that may have succeeded (for example after a timeout), call list first to check whether the item already exists, so you do not create it twice.

Authentication errors

Message	Cause and solution
`key does not exist`	The key is wrong or was deleted. Check it in API Manager.
`No special characters are allowed!`	The key contains characters other than letters and numbers — usually a copy-paste problem (spaces, quotes).
`unauthorized host`	The request did not come from the key’s Ip Origin. Check the public IP of the calling server (behind NAT it may differ) and update the key.
`Key off`	The key is switched off in API Manager.
`Unauthorized action …`	The key does not have permission for this function and action. Switch it on in API Manager.

Validation errors

Message	Meaning
`All data is required` / `Some data is required`	A required parameter is missing
`Check All Fields (only lower caps are allowed and no special characters or empty spaces...`	The username or domain is invalid, or the username already exists
`user does not exist`	The `user` parameter is not an existing hosting account
`Something went wrong`	The operation failed on the server — check the parameters (for example `changepack` needs the package ID)

Unexpected HTML instead of JSON

If a required parameter is missing or has the wrong name, some functions return an HTML page titled Slim Application Error instead of JSON. This is not a server outage: compare your parameters with the function page (for example email updates need mailbox, not email). Treat any non-JSON response as an error.

Logging and debugging

Every call is logged on the server in /var/log/cwp/cwp_api.log with the date, the key and whether it was authorized.
Send debug=1 with a request to write extra debugging information to the server log for functions that support it.