Skip to content

Common error responses

Conventions

Standard 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"
}

Multi-errors format

PATCH endpoints can sometimes return multiple errors, either due to multiple field validation or processing errors reported by upstream processes. In these instances, the endpoint will return an array of errors, as follows:

XXX HTTP Error Code
{
    "errors": [{
        "code": "STRING_ERROR_CODE",
        "httpCode": XXX,
        "message": "Detail about the error 1"
    },{
        "code": "STRING_ERROR_CODE",
        "httpCode": XXX,
        "message": "Detail about the error 2"
    }]
}
  • The error array will be returned regardless of the number of errors i.e. if there is only one error, the array will contain a single entry.
  • Each individual error within the array follows the standard error format, as described above.
  • Since each error has its own status code, the HTTP status code returned in the response will be the lowest status code found in the errors.
  • This multi-error format helps developers by providing all the errors raised during the input validation at once, so that corrective action can be taken or reported to an end user.
  • Currently, the only endpoint that displays this behaviour is PATCH /devices/{device-id}.

Error codes

The possible error codes are as follows

httpCode code Possible reasons
204 N/A No 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).
400 BAD_REQUEST The request or one of its parameters are malformed. See the message field for more information.
401 UNAUTHORIZED The provided credentials are not valid or have been disabled.
403 FORBIDDEN The provided credentials are not permitted to access the requested resource.
404 NOT_FOUND The requested resource does not exist OR the provided apiKey does not grant access to it.
422 UNPROCESSABLE_ENTITY The request is well formed, but the parameters are not semantically valid. See the message field for more information.
429 TOO_MANY_REQUESTS_TP* You have exceeded your API key usage limits. Code ending in _TPS = per-second limit exceeded. _TPD = per day limit exceeded.
500 INTERNAL_SERVER_ERROR Something 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."
}