Come usare
- Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
- Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
- Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/sshvarzman-salesforce/claude-skills --skill sf-agent-api-troubleshootingPrima di iniziare
- L’installazione non include abbonamenti, quote API o accesso ai file.
- Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale
Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.
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
