sf-agent-api-troubleshooting
Installation
SKILL.md
Agent API Troubleshooting
Use This Skill When
- An Agent API call returns a non-2xx status and you need the likely cause and fix.
- A call times out or reports an unexpected media-type / config error.
- Diagnosing Government Cloud endpoint mismatches.
Error Matrix
| Status | Meaning | Likely cause | Fix |
|---|---|---|---|
| 400 Bad Request | Malformed request | Message contains "{VALUE} is not a valid agent ID" | Verify the agent ID (re-fetch via BotDefinition or Legacy URL) |
| 401 Unauthorized | Auth problem | Bad/expired token, flow not enabled | Re-mint token; confirm client credentials flow + Run As user |
| 404 Not Found | Wrong token or endpoint | Incorrect host/path; gov cloud on standard host | Verify endpoint; gov cloud must use api.gov.salesforce.com |
| 423 Locked | Session already locked | Concurrent request on the same session | Serialize turns; only one request in flight per session |
| 500 Internal Server Error | Server-side / config error | See sub-causes below | Match the message/error field below |