Troubleshooting
An index, not an explainer. Find the symptom, follow the link to the page that owns it.
The API returned an error
Section titled “The API returned an error”Every failure from /v1 carries a machine-readable code and a docs_url. The full table with status codes and prose is at errors.
| Code | Usually means |
|---|---|
invalid_api_key | Missing, malformed, revoked, or unknown key |
bad_request | Malformed body, no records, or a record the model could not featurize |
record_limit_exceeded | More than 1000 records in one batch call · split it |
model_not_found | The model_id does not exist for your org |
quota_exceeded | Scoring is paused for the month · see limits |
rate_limited | Too many requests per second for that key · slow down and retry |
internal_error | Unexpected server error · safe to retry with backoff |
Scoring stopped part way through the month
Section titled “Scoring stopped part way through the month”You passed the included allocation, went through the grace band, and hit the backstop. How usage accrues explains what moved the meter; limits has the allocation per plan.
Check the usage object in the last successful batch response before you assume anything else: in_grace: true with a negative remaining says exactly where you are.
Scores came back but they look thin
Section titled “Scores came back but they look thin”A record with no history here is scored on the fields in your request and nothing else. The batch response marks it as not enriched rather than padding it. Cold records covers the flag, and the live scoring API covers what to do with it.
An agent was refused
Section titled “An agent was refused”The MCP server refuses in plain language rather than failing silently.
- Credentials and what each tool needs · authentication
- Which tools meter and which never leave your machine · limits and metering
- What a tool is allowed to send anywhere · what leaves your org
A tool that names a credential you have not supplied is telling you the truth about what it needs. Supply it rather than retrying.
The model will not train, or trained badly
Section titled “The model will not train, or trained badly”These are data problems far more often than model problems, and the product names each one before you train.
- Dataset health · the diagnostics wall and what each check is looking at
- Target leakage · a field that already knows the answer
- Redundant fields · two fields carrying the same signal
- Records trained · how many rows actually reached the model
- Success criteria · what the model was told to predict
The score is not what I expected
Section titled “The score is not what I expected”- Conversion likelihood · what the number is
- Score factors · why one record scored the way it did
- AUC and lift curve · how to judge the model rather than one record
- Score distribution · when the shape itself is the finding
Scores are not reaching the CRM
Section titled “Scores are not reaching the CRM”Activation and refresh covers writeback, cadence, and activation. Salesforce covers the connection itself, including which path to use and the limits on it.
None of the above
Section titled “None of the above”Contact support. Include what you ran, what came back, and the timestamp.
- Errors · the full code table
- Limits and what is included
- Learn · every concept, how-to, and check, by category