Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/sshvarzman-salesforce/claude-skills --skill sf-agent-api-troubleshootingAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
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 |
HTTP 500 sub-causes
| Message/Error field contains | Cause | Fix |
|---|---|---|
| "Unsupported Media Type" | Wrong Content-Type | Set Content-Type: application/json |
EngineConfigLookupException | Wrong domain in start session | Use the Current My Domain URL for instanceConfig.endpoint (not Lightning URL) |
HttpServerErrorException | Wrong agent ID in endpoint | Use the correct agent ID (see sf-agent-api-setup) |
| (timeout) | Call exceeded 120s | The API times out at 120s and returns 500; add client timeout + retry/fallback |
| other | Setup incomplete | Re-verify Get Started setup steps |
Diagnostic Workflow
- Capture status code, response
message/errorfields, andtraceId(from streaming events / logs). - Classify using the matrix above.
- Verify inputs in order: token validity → base host (standard vs gov) → agent ID →
instanceConfig.endpoint(My Domain) → headers (Content-Type,Accept). - Check concurrency if 423 — is another turn still in flight for this session?
- Re-test the isolated call (curl / Postman) before changing client code.
Guardrails
- Log
traceId,sessionId, and the HTTP status on every failure — support cases needtraceId. - Never retry a 423 immediately in a tight loop; wait for the in-flight turn to complete.
- Distinguish transient 500 (timeout, server) from deterministic 500 (config, media type) before retrying.
- On Government Cloud, a 404 usually means the standard host was used — switch to
api.gov.salesforce.com. - Re-minting the token fixes most 401s; if not, the flow/Run As configuration is wrong.
Deliverables
- A triage note per failure: status, cause, fix, and whether it's transient or deterministic.
- A retry/backoff policy that treats 423 and deterministic 500s as non-retryable-as-is.
Additional Resources
- Setup and correct endpoints:
sf-agent-api-setup - Concurrency/session rules:
sf-agent-api-session-lifecycle - Resilience design:
sf-agent-api-integration-patterns - Official docs: Agent API Troubleshooting, Considerations
