Errors and troubleshooting

Read the status and the text

Error bodies can be plain text. Keep the status, endpoint, UTC time and response text when asking support for help. Exclude credentials and customer personal data from logs.

A request body that exceeds the accepted size can return 413. Reduce the request size and query scope. For transient 5xx responses, use bounded backoff; do not retry indefinitely.

Troubleshooting

List works, but /session returns 401 “not found”

Send the exact session_id from a list row in the x-session-id header, with the same Bearer key. A session_id query parameter or JSON body is ignored. “not found” means the session could not be located, not that you need a transcript scope. If correct headers still fail, contact support with the session ID, endpoint, status, response text and UTC time; never include your API key.

401 “not permissioned” or “not authorized”

The user behind the key cannot read that session or team. Check /visible and ask your team admin to review reporting access. A team_id parameter does not grant access. “inactive user” can also mean the key is invalid or the account is inactive.

401 “not on db”

The backend found the session record but could not load its stored detail. Report the session ID and response text to support. You can still use transcript columns from the list when available.

400 or rejected phone, company, email or transcript field

Use the exact paths in the field guide. start and select are required for lists; metrics use selects. POST parameters belong in JSON, with Content-Type: application/json. Error responses can be plain text.

200 with [] or missing contact/transcript values

Confirm the UTC date window, readable reps and filters. Remove the live-duration filter to include short calls. Contact data depends on captured CRM enrichment; transcripts depend on recording/transcription settings. A 200 empty result is a successful query with no matching readable rows.

429 Too Many Requests

Wait the Retry-After number of seconds, then retry with a bounded retry policy. Coordinate workers using the same user key. Default backend limits are per user, not per IP. If only your shared cloud host is blocked despite pacing, give support the UTC time, endpoint and response headers so upstream limits can be investigated.

I need every call, not just the newest 50

Set limit to at most 1000. There is no cursor or offset pagination. If a window fills the limit, split it into smaller [start, end) windows and deduplicate by session_id. A full 1000-row response does not prove the export is complete; very dense windows may also need rep filters.

I need a team-wide read-only key, or my key was exposed

A Trellus API key belongs to a user and inherits their permissions; using it for reporting does not make it a separately restricted credential. Each user can copy their own key in Settings → Integrations → API. Use an appropriately permissioned account for team reporting, verify /visible, and contact support for key replacement if it was exposed.

Limits and pacing are on Rate limits and exports. For anything else, contact Trellus support.