Delivery and polling

The Python call is blocking, but the API produces results asynchronously.

Request lifecycle

  1. The client constructs and serializes a value, report, or application request.
  2. It sends an HTTP POST to the configured Pacífico API endpoint.
  3. The token is carried in the x-api-key header.
  4. The initial response body is interpreted as a temporary result URL.
  5. The client repeatedly sends HTTP GET requests to that URL.
  6. Polling continues while the body contains processing or <Error>.
  7. The first body without either marker is treated as the final payload.
  8. The payload is converted to the requested local format and optionally saved.

The package's Python workflow uses POST; raw GET endpoint semantics are not part of this client contract.

Poll controls

result = pacifico.request(
    "token.key",
    ticker="CHILE",
    timeOut=600,
    timeFrecuency=1.0,
)
Parameter Default Meaning
timeOut 300 Maximum elapsed seconds allowed by the polling loop
timeFrecuency 0.5 Seconds slept between “still processing” polls

The misspelling timeFrecuency is the implemented public keyword. timeFrequency is captured as an unused extra keyword on value/report routes and does not change polling.

Use a positive numeric timeout and a non-negative interval. Very small intervals increase request volume; very large intervals increase completion latency.

What timeOut does not cover

The current HTTP calls do not pass a socket-level timeout to requests.post or requests.get. timeOut controls only elapsed time inside the polling loop. A stalled network call can therefore exceed it.

The initial POST also occurs before the polling timer starts.

For normal application execution, the preliminary help lookup has its own fixed 300-second polling limit. The outer timeOut applies only after that setup stage.

Completion detection

Completion detection is based on literal response text, not an HTTP status machine:

  • processing means keep polling;
  • <Error> also means keep polling;
  • any other body is considered complete.

Matching is case-sensitive. HTTP status codes are not explicitly checked and raise_for_status() is not called. A proxy page, authentication body, or server error that lacks those markers may reach the conversion layer as though it were a successful payload.

Raw JSON is therefore valuable during diagnosis:

payload = pacifico.request(
    "token.key",
    ticker="CHILE",
    format="json",
    timeOut=600,
)

Timeout behavior

When a processing response remains after the elapsed limit, the client raises:

TimeoutError: The time out limit (<SECONDS> seconds) has been exceeded.

A timeout does not establish that server-side work was cancelled; it only means the client stopped waiting. Avoid immediately launching many duplicate large requests.

Retry strategy

The client does not implement retry limits, exponential backoff, jitter, or status-aware retry classification. If the application adds retries:

  1. retry only known transient failures;
  2. cap attempts and total elapsed time;
  3. back off between attempts;
  4. avoid retrying invalid arguments or authentication failures;
  5. consider whether duplicate application execution has side effects;
  6. log a request correlation identifier if the service supplies one, but never the token or result URL.

Sizing and concurrency

  • Narrow selectors and metadata-informed requests reduce result size.
  • Increase timeOut for legitimately large reports or hosted applications.
  • Use a moderate timeFrecuency when many workers operate concurrently.
  • Avoid unbounded fan-out; each call performs its own polling loop.
  • DataFrame conversion is additional local work after delivery.
  • Browser-typed report conversion uses a shared filename in the current working directory and opens browser windows, so it is unsuitable for parallel unattended conversion.

The package has no async coroutine API. To integrate with an async program, isolate blocking calls in a bounded worker pool and apply application-level concurrency limits.

Sensitive delivery artifacts

Treat temporary result URLs as bearer-like sensitive artifacts even though the public function normally keeps them internal. Do not emit request headers, tokens, result URLs, or licensed payloads to routine logs. See Security.