The following are proposed error responses for different use cases. Not all error responses are currently implemented, however the HTTP status codes should match those outlined below.

Please notify the Wattwatchers team if you encounter an incorrectly formatted error or a different error code than that specified so we can rectify or update the documentation accordingly.

Conventions

Format

Error payloads follow the format of the v2 API. The specific content of error messages may differ slightly between API versions.

XXX HTTP Error Code
{
    "code": "STRING_ERROR_CODE",
    "httpCode": XXX,
    "message": "Detail about the error"
}

Error codes

The possible error codes are as follows

httpCodecodePossible reasons
204N/ANo content. This is not technically an "error" (thus returns a 20x response), but the request results in no data being returned, which may appear to be an error, so is included here for reference. For example, if requesting energy data when there is none stored/available for a device (e.g. it has yet to be installed/initialised).
400BAD_REQUESTThe request or one of its parameters are malformed. See the message field for more information.
401UNAUTHORIZEDThe provided credentials are not valid or have been disabled.
403FORBIDDENThe provided credentials are not permitted to access the requested resource.
404NOT_FOUNDThe requested resource does not exist OR the provided apiKey does not grant access to it.
422UNPROCESSABLE_ENTITYThe request is well formed, but the parameters are not semantically valid. See the message field for more information.
429TOO_MANY_REQUESTS_TP*You have exceeded your API key usage limits. Code ending in _TPS = per-second limit exceeded. _TPD = per day limit exceeded.
500INTERNAL_SERVER_ERRORSomething went wrong at our end. There has been a server problem processing your request. Our operations team is alerted in case of any server errors.

400 vs. 422 errors

400 status code are returned when the content of a request or query string is malformed or not in the correct format (e.g. if a string is provided when an integer was expected).

422 status code will be returned when the content of a request is well formed and in the correct format, but the contents are not semantically correct, or the request can't be fulfilled for some other reason. For example, the time period represented by fromTs and toTs is too long for the granularity.


Example errors

No energy data

If the device has not yet registered energy data (for example Long Energy, Short Energy or modbus data), the API returns:

204 No Content

This is not technically an error (thus the 20x status code), but may seem like an error as there's no content returned. This is returned for both singular (e.g. first and latest) and lists of energy data (e.g. the long-energy/{device-id} endpoint).

If the device has registered energy data (for example Long Energy, Short Energy or modbus data), but there is no energy data for the period specified (i.e. between fromTs and toTs) an empty list will be returned:

200 OK

[]

Incorrect Content-Type header

When specifying data (e.g. in a PATCH request), the request body should be in JSON format, and the Content-Type header must be application/json.

400 Bad Request
{
    "code": "BAD_REQUEST"
    "httpCode": 400,
    "message": "The Content-Type header must be 'application/json'."
}

Missing/malformed data in request body

400 Bad Request
{
    "code": "BAD_REQUEST",
    "httpCode": 400,
    "message": "Serial numbers must be 13 characters in length, starting with a B, D, E, F."
}

Access to resource not authorized

403 Forbidden
{
    "code": "FORBIDDEN",
    "httpCode": 401,
    "message": "You don't have permission to access device D123456789012."
}

Device not found

If the device ID is not recognised by the system, a 404 will be generated.

404 Not Found
{
    "code": "NOT_FOUND",
    "httpCode": 404,
    "message": "D123456789012 could not be found."
}

No Bearer authentication header provided

401 Unauthorized
{
    "code": "UNAUTHORIZED",
    "httpCode": 401,
    "message": "You must provide a valid Authorization header value to access this endpoint."
}

API key not provided

If you provide a Authorization header, but no bearer token:

401 Unauthorized
{
    "code": "UNAUTHORIZED",
    "httpCode": 401,
    "message": "You must provide a valid Authorization header value to access this endpoint."
}

Invalid/unrecognised API key

If the API key is not recognised, you will receive a Not Permitted response:

{
    "code": "NOT_PERMITTED",
    "httpCode": 403,
    "message": "You are not permitted to access this endpoint with the provided token."
}

Rate limiting triggered

In the examples below:

X-RateLimit-Reset represents the timestamp (seconds since epoch) when the limit is reset.

Retry-After is the number of seconds from now where issuing a new reqest will be processed without triggering the same limit.

TPS (per second) threshold

429 Too Many Requests
X-RateLimit-Remaining: 0
X-RateLimit-Limit: 5
X-RateLimit-Reset: 1550549481
Retry-After: 1
{
    "code": "TOO_MANY_REQUESTS_TPS",
    "httpCode": 429,
    "message": "You have exceeded the request limit of 5 per 1 second for for your API key. Please review the response headers for further details."
}

TPD (per day) threshold

429 Too Many Requests
X-RateLimit-Remaining: 0
X-RateLimit-Limit: 10000
X-RateLimit-Reset: 1550635880
Retry-After: 86398
{
    "code": "TOO_MANY_REQUESTS_TPD",
    "httpCode": 429,
    "message": "You have exceeded the request limit of 10000 per 1 day for for your API key. Please review the response headers for further details."
}

If there is no X-Rate... or Retry-After headers and the response body is not formatted as above, the overall server rate limiting has been engaged in response to too much traffic (i.e. this is not in response to your API limits). In such a circumstance we will be notified and be working to resolve the issue.

Missing/invalid required parameter

If a required parameter is not provided:

400 Bad Request
{
    "code": "BAD_REQUEST",
    "httpCode": 400,
    "message": "You must specify the fromTs query string value."
}

Invalid start or end timestamp

422 Unprocessable Entity
{
    "code": "UNPROCESSABLE_ENTITY",
    "httpCode": 422,
    "message": "The provided {{fromTs|toTs}} ({{timestamp}}) value was invalid."
}

Period > valid values for granularity

In the event that an invalid time period is specified—e.g. toTs minus fromTs exceeds the maximum time period, a 422 will be returned:

422 Unprocessable Entity
{
    "code": "UNPROCESSABLE_ENTITY",
    "httpCode": 422,
    "message": "The requested time period is greater than 7 days."
}