Errors and troubleshooting

The client mixes raised exceptions, returned error objects, and synthetic DataFrame rows. Diagnose from the narrowest request and rawest representation.

First diagnostic request

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

print(raw)

Sanitize the payload before sharing it. Never share the token, request headers, or temporary result URL.

Symptom matrix

Symptom Likely cause Action
FileNotFoundError Empty token looked for ./token.key, or explicit .key/.txt path is wrong Pass an absolute or correct relative path
Authentication appears to fail Invalid/revoked token or whitespace in token file Rotate if needed; ensure the file contains only token characters
TypeError mentioning date Date passed as a string or incompatible object Pass datetime.date values
ValueError about dateEnd End precedes start Correct the interval
TypeError mentioning fixing/quality/version String or int passed instead of exported enum Import and pass the enum member
TimeoutError Result remained in processing beyond the polling limit Narrow the request or increase timeOut; avoid duplicate storms
Call hangs beyond timeOut Network request itself stalled timeOut is not a socket timeout; investigate network/proxy behavior
JSON decode error in dictionary mode Final body is not valid JSON Retry the same narrow request with format="json"
DataFrame with Ticker == "Error" Value conversion or short service error Inspect Value and Other, then inspect raw JSON
DataFrame with Document == "Error" Report/application conversion failed Inspect Value/Other and raw JSON
Empty or unexpected history Server normalized the selector/date combination Review Dates and history and validate returned dates
Requested author not respected Current path omits the version predicate Filter and validate Scenario/Author client-side
Intraday value returns a DataFrame error row Publication key contains -F_HHMM, which the value DataFrame parser does not accept Request format="json" or "dictionary" and preserve the fixing suffix
Latest value missing although older history exists Latest value is older than 500 days Make an entitled historical request for a known date/range
Browser opens during report parsing Report contains a scalar Browser variant Use format="json" or "dictionary"
browser.html/Selenium warning Browser variant could not be displayed Use raw format; ensure Chrome/Selenium only if display is intended
File saved with double extension Extension included in fileName Pass a base path without .csv/.txt
Output directory error Parent directory does not exist Create it before the request
dataType or timeFrequency has no effect Wrong keyword silently captured by **kwargs Use fieldType and timeFrecuency exactly
Application fails before running Preliminary help lookup or file upload failed Fetch help=True directly and verify files/contract

Detect DataFrame error rows

def raise_for_error_row(frame):
    if "Ticker" in frame.columns:
        failed = frame["Ticker"].astype(str).eq("Error")
        if failed.any():
            row = frame.loc[failed].iloc[0]
            raise RuntimeError(
                str(row.get("Other") or row.get("Value") or "Value request failed")
            )

    if "Document" in frame.columns:
        failed = frame["Document"].astype(str).eq("Error")
        if failed.any():
            row = frame.loc[failed].iloc[0]
            raise RuntimeError(
                str(row.get("Value") or row.get("Other") or "Report request failed")
            )

Also validate required columns. The short-error DataFrame always uses the value schema, even for a report call.

Unexpected route

Check arguments in this order:

  1. Is app non-empty? The request is an application.
  2. Is any report selector non-empty? The request is a report.
  3. Otherwise it is a value request.
  4. An empty value selection with empty author becomes value metadata.

If only chapter/section/subsection/paragraph is provided, add document or item.

Unexpectedly broad field result

fieldType recognizes a fixed, case-insensitive list. Unknown input silently maps to unspecified and can return every field:

ALLOWED_FIELDS = {
    "price",
    "yield",
    "duration",
    "convexity",
    "delta",
    "gamma",
    "vega",
    "volatility",
    "quote",
    "clean price",
    "clean quote",
    "market presence",
}

requested = user_field.casefold()
if requested not in ALLOWED_FIELDS:
    raise ValueError(f"Unsupported field: {user_field}")

Polling and HTTP errors

The client does not inspect HTTP status codes explicitly. A non-JSON error page can be treated as a completed payload and fail later.

Check:

  • DNS and outbound HTTPS access;
  • TLS interception or corporate proxy behavior;
  • token validity and entitlements;
  • whether the API endpoint is reachable from the runtime;
  • whether a large request should be narrowed;
  • whether a hosted application has a separate upstream failure.

Do not disable TLS verification in application code.

Report type conversion

Report conversion can fail when:

  • variant.type is unknown or has unexpected capitalization;
  • a numeric value cannot be cast;
  • a canonical date does not match DD/MM/YYYY or DD/MM/YYYY HH:MM:SS;
  • a large-response ISO timestamp is invalid;
  • a list element cannot be coerced;
  • browser content cannot be downloaded or displayed.

Use dictionary or JSON mode to inspect source values without conversion.

Escalating to support

Provide:

  • package version;
  • Python and operating-system versions;
  • sanitized request parameters;
  • approximate request time and timezone;
  • route (value, report, or application);
  • requested format, timeout, and polling interval;
  • exception class/message or sanitized error row;
  • a redacted fragment of raw JSON when permitted.

Do not provide the token, private result URL, credential files, full licensed datasets, or confidential application inputs.