Errors & troubleshooting · TruCom Developers

Read the error envelope

Every REST error uses error.code, error.message and error.details. Validation failures include details.fields with field-specific messages. Save the X-Request-Id response header when investigating a failed request; never log the Authorization header or identity token.

JSON

{
  "error": {
    "code": "validation_failed",
    "message": "Check the highlighted request fields.",
    "details": {
      "fields": {
        "email": [
          "The email field must be a valid email address."
        ]
      }
    }
  }
}

Common status codes

Status	Meaning / action
400	Invalid JSON object or missing required Idempotency-Key.
401	Missing, invalid, expired or revoked key; check the Bearer token and ownership.
403	Required scope or current workspace permission is missing.
404	Unknown endpoint or resource unavailable in this workspace.
405	HTTP method is not supported.
409	Idempotency mismatch, missing identity signing or subject bound to another customer.
413	JSON body exceeds 64 KB.
415	Use Content-Type: application/json for write requests.
422	Invalid fields, duplicate identities, quota or other customer validation. Inspect details.fields.
429	Per-key rate limit exceeded. Wait Retry-After seconds.
500	Unexpected failure. Retry with backoff and the same write operation key.

Identity and retry conflict codes

Code	What to check
idempotency_key_required	Add a stable Idempotency-Key to the create or reply request.
idempotency_conflict	Use the original request content or a new operation key.
identity_signing_not_configured	Configure identity signing in Chat widget / Identity.
identity_subject_conflict	Resolve the correct customer for this subject; do not reassign someone else’s history.
insufficient_scope	Grant the exact scope named in error.details.required_scope.
invalid_api_key	Use an active server key whose creator still owns the workspace.

Keep requests predictable

Send JSON objects with application/json. Use ISO 8601 dates from responses and public ULIDs for resource IDs. An API key is permanently scoped to its workspace and widget; a workspace parameter cannot override it.

If the widget is hidden, REST access continues. If a key’s linked widget or workspace is deleted, that key no longer works. Use GET /me to verify a connection before syncing customer data.