FLOW's REST API error reference

When a REST request to FLOW servers is successfully processed, a response with the 200—OK HTTP status code and a JSON body (if relevant) is returned. This document identifies the error codes and messages that FLOW servers return when things don't go as planned. This sample response JSON body demonstrates how an error is communicated:

{
   "error": {
      "code": 400,
      "reason": "invalid_argument",
      "message": "The value for one of the fields in the request body was invalid."
   }
}

code field contains the same value as the actual returned HTTP status code
reason is a short string serving as a more specific nonambiguous error identifier
message is a human-readable message describing the error

Each code has a set of unique reasons that may , but never the same reason for different

FLOW errors are listed by their HTTP status codes as defined in RFC 7231. Within the individual status codes, they are listed by the contents of the reason field.

304—Not modified

not_modified
The conditional request would have been successful, but the condition was false, so no body was sent.

400—Bad Request

bad_request
The API request is invalid or improperly formed. Consequently, the API server could not understand the request.

invalid_parameter
The value for one of the URI parameters was invalid. In addition to normal URI parameter validation, any URI parameters that have a corresponding value in provided JSON request bodies must match if they are both specified.

parse_error
Could not parse the body of the request according to the provided Content-Type.

invalid_argument
The one or more properties in the request’s JSON body are invalid or missing.

required
A required URL parameter or required request body JSON property is missing.

api_version_mismatch
The Accept-Version header is missing, or there is a mismatch between the major version of the client and the block, or the client's minor version is lower than the block's. See the related article for more information about the header, API versioning, and how to find out the block's API version.

sequence_number_format_error
In requests that require you to provide a sequence number, the sequence number's data type must be a string, not an integer.

401—Unauthorized

auth_error
The provided username or password is invalid.

invalid_bearer_token
The provided bearer token in the Authorization header is invalid.

required
Access to a non-public method that requires that a bearer authentication was made, but none has been provided in the Authorization header. See the related article on how to properly authenticate.

session_expired
Your session has expired. Log in again to continue.

403—Forbidden

forbidden
According to the access control policy, the current user does not have access to perform the requested action. This code applies even if the resource being acted on doesn't exist.

account_disabled
The account associated with the resource has been disabled.

404—Not Found

not_found
Either there is no API method associated with the URL path of the request, or the request refers to one or more resources that were not found.

405—Method Not Allowed

method_not_allowed
The HTTP verb is not supported by the URL endpoint used in the request.

409—Conflict

conflict
A request to change a resource failed to commit the change due to a conflicting concurrent change to the same resource.

outdated_sequence_number
In cases where it's important for the client to know the current version of the analytic they are interacting with, a sequence number field is required in the JSON request bodies. A sequence number is basically an analytic's current v*ersion that increments every time it is modified. While performing sink data requests, use the current sequence number. While updating an analytic, use a sequence number 1 higher than the current. Learn here how to obtain the current sequence number.

resource_exists
POST method has been used on an existing element of a collection.

413—Payload Too Large

payload_too_large
The message body was larger than what FLOW supports.

415—Unsupported Media Type

unsupported_media_type
The request's Content-Type header is missing or contains an unsupported format.

429—Too Many Requests

rate_limit_exceeded
The usage limit has been exceeded. If your application tries to use more than its limit, additional requests will fail. Throttle your client's requests.

500—Internal Server Error

internal_error
We encountered an internal error. Please contact us at [email protected] to help us resolve the situation.

501—Not Implemented

not_implemented_yet
The server does not support the functionality required to fulfill the request at the moment.

503—Service Unavailable

analytics_data_loading
Analytics data is loading and currently not available.

What next?

This concludes everything there is to know about FLOW's REST API! If you want to know about other options of obtaining sink data, see UDP sinks for a subscription-based variant of sinks. You can also make FLOW send you widget outputs on its own with webhooks.

Want to learn more? Contact us!