Tool returns 401 or 403

When a tool fails with HTTP 401 or 403, the assistant cannot fetch live data. Visitors may see a generic apology or a text-only fallback.

Symptoms

Where	What you see
Assistant test panel	Tool call red badge; `401 Unauthorized` or `403 Forbidden`
Tool test page	Raw response status from your API
Tool logs	`Tools → Logs` — failed execution with status code
Visitor chat	”I couldn’t look that up right now” (no rich cards)

Diagnosis flow

flowchart TD
  A[Tool fails 401/403] --> B{Test tool in dashboard}
  B -->|Fails| C[Check credential]
  B -->|Works| D[Check param mapping]
  C --> E{Credential type}
  E -->|API key| F[Key valid and sent in correct header?]
  E -->|OAuth| G[Token expired? Re-authorize]
  E -->|Bearer| H[Value matches your API docs?]
  D --> I[strict_params missing required field?]

Fix by cause

Invalid or expired credential

Credentials → open the credential used by the tool.
Re-enter the API key or re-run OAuth authorization.
Tools → Test with sample parameters.

Credential type	Common fix
API key	Regenerate key in your system; update Chatevo
Bearer token	Paste new static token
OAuth 2.0	Click Re-authorize
HMAC	Verify secret matches your server

Wrong header or query placement

Check tool config under Headers and Query params:

Mistake	Fix
`Authorization` duplicated	Chatevo adds credential header — remove manual duplicate
API key in query but server expects header	Move to header per your API docs
Missing `Content-Type` on POST	Add `application/json` header

IP or scope restrictions

Your API may block Chatevo egress IPs or require scopes:

Allowlist Chatevo IP ranges (provided on Enterprise support request)
Ensure OAuth scopes include the endpoint being called

403 on specific resources

The credential is valid but not permitted for the requested resource:

Order belongs to a different account
API key is read-only but endpoint requires write
Role-based access missing for the tested record

Test with a known-good ID from your API docs.

Path and parameter errors

Misconfigured path params can hit protected routes:

GET /orders/{order_id}  →  /orders/undefined  → 403

Enable strict params and verify test inputs.

Verify the fix

Tools → Test — expect 200 and valid JSON.
Assistants → Test — ask a question that triggers the tool.
Check Tools → Logs — latest entry shows success: true.