Responses and errors

The result document

Every data method returns an XML document inside {Method}Result. The document has a root element with one child element per record, for example tlp:Employees with one tlp:Employee per employee. The namespace is http://www.timelog.com/XML/Schema/tlp/v4_4 (prefix tlp). Each method page lists the record's fields.

The same slot carries three different answers. Tell them apart by the root element:

Values

Currencies

Amounts follow a naming rule, unless the method page says otherwise for a field:

Each method page states the currency in the field's label, for example Billable amount (project currency).

Large results

Most methods return all matching records in one response: there is no paging and no row limit. Narrow the result with the method's filters (IDs, status, date range). A call that takes too long fails with HTTP 500. For time registrations, use the paged extract for large accounts.

Checking the result in code

import xml.etree.ElementTree as ET

TLP = "{http://www.timelog.com/XML/Schema/tlp/v4_4}"

def parse_result(response):
    """Return the records of a Reporting API call, [] when nothing matched; raise on errors."""
    if response.status_code == 401:
        raise PermissionError("Access denied: check siteCode, apiID, apiPassword and https")
    root = ET.fromstring(response.content)          # raises if the document is cut off
    result = next(el for el in root.iter() if el.tag.endswith("Result"))
    if result.text in ("true", "false") and len(result) == 0:
        return result.text                            # ValidateCredentials
    doc = result[0]
    if doc.tag == f"{TLP}Errors":
        raise RuntimeError(f"HTTP {response.status_code}: " + "; ".join(e.text for e in doc))
    if doc.get("resultEmpty") == "true":
        return []
    return list(doc)

Errors

These errors can come back from any method. Each method page lists the errors specific to it.