Errors

Branch on the HTTP status and on code. Do not parse message. The Check API writes message in English, and the text of a message can change.

Error envelopeCopy Anchor Link

Every error response of the Check API has the same JSON shape. A response from the network in front of the Check API can have another body. See Answers outside the envelope.

{
  "data": null,
  "code": "validation_failed",
  "message": "Request is invalid.",
  "errorId": "FMS400",
  "traceId": "req_01M6JYA33G9NXKXXSG1B7Q1J4J",
  "errors": [
    {
      "code": "text_too_long",
      "field": "text",
      "inputTokens": 16001,
      "maxInputTokens": 16000,
      "message": "Text is 16,001 input tokens. The limit is 16,000 input tokens."
    }
  ]
}

Treat traceId and X-Request-Id as opaque strings. Most IDs start with req_, but a 400 or a 503 from the network in front of the Check API carries an ID in another form.

Error codesCopy Anchor Link

The Check API handles a request in this order: the path, the key, the body, and the limits. Then it checks the text. A request with a bad key and a bad body gets 401. A 400 or a 401 uses none of the rate limit and none of the monthly quota.

Field errorsCopy Anchor Link

A 400 validation_failed response has one item in errors.

When the body has more than 4 MiB, the Check API stops reading it. The text_too_long item then has maxInputTokens but no inputTokens.

{
  "data": null,
  "code": "validation_failed",
  "message": "Request is invalid.",
  "errorId": "FMS400",
  "traceId": "req_01M6JYA248KMF0WBCMB786A8XD",
  "errors": [
    {
      "code": "text_empty",
      "field": "text",
      "message": "Text is empty."
    }
  ]
}

Answers outside the envelopeCopy Anchor Link

Some responses that do not come from the Check API have a body that is not the error envelope.

• The network in front of the Check API can answer 403 with a plain body that is not JSON. It does so, for example, when a client sends far too many requests or a request looks malicious.
• The load balancer can answer 502, 503, or 504 with an HTML body when the Check API is not available.

These responses have no code, errorId, or traceId, and they can lack the headers in Response headers. Handle them in your app.

• Read the body as JSON only when the Content-Type of the response is application/json.
• Do not retry a 403 that is not JSON right away. Send fewer requests and check what you send. If the 403 keeps coming, contact support with the time of the requests.
• Retry a 502, 503, or 504 with an HTML body with backoff, as in Retry 500 and 503.

Retry 500 and 503Copy Anchor Link

A 500 or a 503 has no result for the text. Your app decides whether to block the text or to send it on without a check.

To retry, wait longer before each retry.

1. Wait 1, 2, 4, 8, and then 16 seconds before the retries.
2. Add a random part of up to 1 second to each wait, so that your servers do not retry at the same moment.
3. Stop after 5 retries.

The samples also retry a 502 and a 504, which come from the load balancer. See Answers outside the envelope.

import os
import random
import time

import requests

MAX_RETRIES = 5


def check(text):
    for attempt in range(MAX_RETRIES + 1):
        response = requests.post(
            "https://api.jp.flowmask.ai/api/v1/check",
            headers={"Authorization": f"Bearer {os.environ['FLOWMASK_API_KEY']}"},
            json={"text": text},
            timeout=30,
        )
        if response.status_code not in (500, 502, 503, 504) or attempt == MAX_RETRIES:
            return response
        time.sleep(2**attempt + random.random())

Keep these facts in mind when you retry.

• A 503 can come after the Check API counted the request against the rate limit. Retries then use more requests of the minute.
• Only a 200 uses input tokens. Every 200 counts the tokens of its text, even when the same text came in an earlier request.
• Do not retry a 429 with this loop. Rate limits and quota explains how to handle each 429.