Rate Limits & Error Handling

Understand API limits, error responses, and how to handle them gracefully.

Error Responses

Floodlight AML uses standard HTTP status codes and returns errors in RFC 7807 format:

Code	Meaning	Common Causes
400	Bad Request	Invalid JSON, missing required fields
401	Unauthorized	Missing/invalid API key, expired token
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
422	Unprocessable	Validation errors
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server issue — retry with backoff
503	Service Unavailable	Maintenance or temporary outage

Error Response Format

JSON

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed",
  "instance": "/v1/screen-entity",
  "errors": [
    {
      "field": "name",
      "message": "Name is required"
    },
    {
      "field": "entityType",
      "message": "Must be INDIVIDUAL or ORGANIZATION"
    }
  ]
}

Server-Side Retry

The API automatically retries failed requests on transient errors with exponential backoff:

Attempt	Backoff
1st retry	~1 second
2nd retry	~2 seconds
3rd retry (final)	~4 seconds

Retry Conditions

Retries are only triggered for server errors (5xx), network timeouts, and connection failures. Client errors (4xx) are never retried.