Troubleshooting¶

401 / 403 errors¶

Verify your API key is correct.
Ensure the key has access to the entities you’re querying.

404 immediately after create¶

If you get a 404 NotFoundError when calling get() right after create(), this is due to V1→V2 eventual consistency. The entity exists but hasn't propagated to V2 yet. This typically resolves within 100-500ms, but can take longer under load.

Solutions: - Use the object returned by create() directly (recommended) - Use get(..., retries=3) to retry with backoff

See V1→V2 eventual consistency for details.

Stale data after update¶

If get() returns old values after calling update(), this is also due to V1→V2 eventual consistency. The update succeeded, but V2 hasn't synced yet. Like the 404 case, this typically resolves within 100-500ms.

Solution: Use the object returned by update() directly - it contains the updated data.

See Stale data after update for details.

Underscores escaped in note content¶

When you create or update a note, the Affinity API escapes underscores in the content:

Input:  "test_note_content"
Output: "test\_note\_content"

This is server-side markdown escaping and cannot be prevented. If you need to search for or compare note content, account for this transformation:

# When checking note content, allow for escaped underscores
original = "my_note"
from_api = note.content
assert from_api in (original, original.replace("_", r"\_"))

Rate limits¶

The client tracks rate-limit state and retries some requests automatically. See Client and Exceptions.

Debugging¶

Enable hooks or set log_requests=True on the client.

CLI: Disable update notifications¶

The CLI shows update notifications in interactive sessions. To disable:

For a single command:

xaffinity --no-update-check person ls

Via environment variable:

export XAFFINITY_NO_UPDATE_CHECK=1

Via config file (~/.config/xaffinity/config.toml):

[default]
update_check = false

Automatic suppression: Notifications are automatically hidden when using --quiet, --output json, in CI environments, or when not attached to a terminal.

See CLI Update Notifications for more details.