Regional Relocation

A site can require connections through one host, such as its custom domain or a regional subdomain. Files.com answers a request that reaches another host with HTTP 403. Its not-authenticated/lockout-region-mismatch error names the host in data.host or the X-Files-Host header; a supplied data.host takes precedence. The SDK also recognizes the legacy plain-text HTTP 403 response starting exactly You have connected to a URL with X-Files-Host. Both forms raise LockoutRegionMismatchError when relocation is refused.

The SDK then sends the operation to that host once, with the same request, when all of these hold:

  • The answer came straight from the operation's current API origin, over HTTPS with the certificate verified, not through a redirect or from file storage.
  • The host is a DNS name, as a bare name or an https:// origin without a path, on the default port, and not a local name such as localhost or an IP address.
  • region_policy is "automatic", the default, and the region_handler, if any, allows it.
  • The request has a retry left. The move counts as one of its max_network_retries, like a retry after a failure, so with 0, or once earlier failures have used them all, the operation raises the error instead.

The new host lasts for the rest of that operation, including a list's later pages and the objects the operation returns. It never changes the client: its next operation starts at base_url again. A second mismatch raises the error instead of moving again.

Controlling Relocation

With region_policy="disabled", for a client or a single call, the operation raises the LockoutRegionMismatchError, retaining the response's data and headers.

A region_handler is called with a files_sdk.RegionRelocation whose original_origin and target_origin are the hosts involved and whose automatic says whether the SDK would move on its own. It returns True to allow that, False to raise the error instead, or an https:// origin to send the operation to, which it approves explicitly, even on another port. If it raises, the operation stops with its exception.

During automatic handling, an iPaaS integration can save an approved target_origin in the handler and use that address as base_url for later calls.

Example Request

import files_sdk

try:
  def only_our_domains(relocation):
    return relocation.target_origin in ("https://files.example.com", "https://eu.files.example.com")
  
  client = files_sdk.Client(
    api_key="YOUR_API_KEY",
    base_url="https://files.example.com",
    region_handler=only_our_domains,
  )
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

Local Development

A base_url over plain HTTP, or with certificate verification off, never relocates automatically. To let a development server send the SDK to another, name the exact pair of origins in region_development_origins.

Example Request

import files_sdk

client = files_sdk.Client(
  api_key="YOUR_API_KEY",
  base_url="http://localhost:3000",
  region_development_origins=[("http://localhost:3000", "http://localhost:3001")],
)