Response Codes

When you make an HTTP request, the Surfact API returns standard HTTP status codes to indicate success or failure.

Code	Meaning	What it means
200	OK	Request successful.
201	Created	Request successful and a resource (device or variable) was created.
202	Accepted	Request accepted for processing, but not yet completed.
204	No Content	Request successful and there is no response body to return.
400	Bad Request	A field is incorrect and the request was not saved. The JSON body or a query-string parameter failed validation — body errors come back as `{"code": 400001, "message": "Validation Error.", "detail": {...}}` naming the offending fields, while query-string problems (such as a non-numeric `start` or a `page_size` below 1) come back as a `detail` or `message` string. Verify your JSON is valid, fields match the expected types (string, object, or float), and your query parameters are in range.
401	Unauthorized	Invalid or missing API key. Check your token — see Authentication.
402	Payment Required	Check your account balance.
403	Forbidden	Your token is valid, but the account lacks permission for this resource (`{"detail": "You do not have permission to perform this action."}`), or the request violates an account limit such as data retention (code `403003`). A missing or wrong token returns 401, not 403.
404	Not Found	The requested resource doesn't exist. Check for typos in device/variable labels, IDs, or the request URL.
405	Method Not Allowed	This endpoint doesn't support the HTTP method used. See the reference for allowed methods.
415	Unsupported Media Type	The request payload format is not supported.
420	Rate Limit Exceeded	You've exceeded your API limits. Contact support to upgrade.
423	Locked	The device is disabled and cannot receive data.
429	Too Many Requests	Rate limiting in effect. Reduce request frequency.
50x	Server Error	Surfact is experiencing server issues. Check the status page or try again later.

Error response format

Authentication errors return a code and message. Surfact returns a single authentication-failure code, 401002, whether the token is missing, empty, or wrong:

{
  "code": 401002,
  "message": "Incorrect authentication credentials."
}

Validation errors (such as malformed JSON) return a detail field:

{
  "detail": "JSON parse error - Expecting value: line 4 column 22 (char 121)"
}

📘
Still stuck on a non-200 response? Email [email protected].

Error response format

Still stuck on a non-200 response? Email [email protected].

Still stuck on a non-`200` response? Email [email protected].