The Agent Service Reasoner manages agent conversations on two surfaces: the multi-agent orchestration layer, where connected subagents collaborate to complete complex tasks, and the single-agent reasoning endpoint, where individual agents process requests from users and calling applications. Errors from this service typically indicate that a request was malformed or missing required context, that the requested agent or session couldn’t be found, that the caller lacked permission, or that a language model call timed out, was rate limited, or encountered a service-side failure.
A2A_BAD_REQUEST
A request to the multi-agent orchestration service was malformed or contained invalid parameters. The service received the request but rejected it because of an unsupported message type, invalid input variables, or a request structure it couldn’t process. Retrying the same request won’t help. The request itself needs to be corrected first.
This error occurs when:
The request was missing required fields or used an unsupported message type.
The agent’s input variables were invalid: wrong types, unknown variable names, or malformed values.
The request structure didn’t match the format the service expects.
How to Troubleshoot
To resolve this error:
Check the detail field in the error response. It includes a specific reason for the rejection.
Validate the request against the connected subagent’s configuration before resending.
If you constructed the request manually, compare it to a working example from the agent’s published configuration.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: A2A_BAD_REQUEST
A redacted copy of the request
A2A_CONFLICT
Another task is already in progress for this conversation. The service rejected the new request to prevent concurrent tasks from corrupting the conversation’s state. Wait for the active task to finish and try again.
This error occurs when:
A follow-up message was sent before the previous task finished.
A retry of an earlier request arrived while the original task was still running.
How to Troubleshoot
To resolve this error:
Wait at least 5 seconds for the active task to complete, then try again. If your agent typically runs longer tasks, you may need to wait longer before trying again.
Send requests for a conversation one at a time. Don’t start the next task until the previous one returns its final response.
If the conflict continues well beyond the expected task duration, check trust.salesforce.com for known incidents.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: A2A_CONFLICT
The conversation context ID and the approximate time when the conflict occurred
A2A_DESERIALIZATION_ERROR
A request to the multi-agent orchestration service failed validation before it was processed. The request structure or data types didn’t match the expected format. Retrying the same request won’t help. The request needs to be corrected first.
This error occurs when:
A field has the wrong data type, such as a number where text is expected.
A required field is missing from the request or the connected subagent’s configuration.
The request contains malformed content, such as invalid characters or missing brackets.
How to Troubleshoot
To resolve this error:
Check the detail field in the error response. It identifies which field failed and why.
Compare your request to the connected subagent’s published configuration to verify the expected format.
If you’re constructing the request manually, validate it before sending.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: A2A_DESERIALIZATION_ERROR
The full detail text from the error response (it identifies the failing field)
A redacted copy of the request
A2A_NOT_FOUND
The agent, session, or task referenced in the request couldn’t be found. It may not exist, may have expired, or may not be accessible to the authenticated user. Retrying won’t help. The identifier needs to be correct before the request can succeed.
This error occurs when:
The agent ID doesn’t match a registered agent.
The task or session ID has expired or was never created.
The request references a resource that belongs to a different org or user.
How to Troubleshoot
To resolve this error:
Verify the agent, task, or session ID is correct and hasn’t expired.
If the resource was created earlier in a flow, confirm it hasn’t been cleaned up.
Confirm you’re authenticated as the user who owns the resource.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: A2A_NOT_FOUND
The agent ID, task ID, or session ID the request was targeting
A2A_PAYLOAD_TOO_LARGE
The request to the multi-agent orchestration service exceeds the size limit. The service rejected it before processing. Reduce the size of the request before retrying.
This error occurs when:
A field in the agent’s input variables contains embedded file data that should be passed as a reference instead.
Input variables have accumulated data across multiple turns and the total has grown too large.
The full conversation history is being resent with each request instead of relying on the session state.
How to Troubleshoot
To resolve this error:
Identify which input variables are largest and reduce or remove them.
Replace embedded file data with references the agent can look up on demand.
Remove accumulated history the agent doesn’t need to see again.
Resend the request with the reduced input.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: A2A_PAYLOAD_TOO_LARGE
The approximate size of the request
A2A_SECURITY_ERROR
The authenticated user doesn’t have permission to perform this action. The identity was confirmed, but the account lacks the required access to the agent or session being requested. Retrying won’t help. The permissions need to change first.
This error occurs when:
The user doesn’t have the required permission set for the agent.
Your org’s settings don’t allow this type of access for this user.
The request is targeting an agent, task, or session that belongs to a different user or org.
How to Troubleshoot
To resolve this error:
Confirm the user’s permissions include access to the agent they’re trying to reach.
If acting on behalf of another user, verify that delegated access is in place.
If access should be allowed, contact your Salesforce admin to review the permissions.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: A2A_SECURITY_ERROR
The agent ID or task ID the request was targeting
A2A_SYSTEM
This error code indicates an unexpected system error and not an issue with your configuration. If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: A2A_SYSTEM
Any context that might help with the investigation, such as when the error occurred, what you or your end user were doing at the time, and whether you’re able to reproduce it
A2A_TIMEOUT
A request to the multi-agent orchestration service timed out before it completed. This is usually a temporary issue. Wait a moment and try again.
This error occurs when:
A reasoning step or AI model call took longer than the allowed time.
A platform dependency was slow or under load when the request was made.
How to Troubleshoot
To resolve this error:
Wait at least 2 seconds, then try again. Most timeouts are temporary.
If the request consistently times out, try simplifying it: use fewer input variables or a shorter prompt.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: A2A_TIMEOUT
Whether retries also timed out
A2A_UNAUTHORIZED
The request to the multi-agent orchestration service couldn’t be authenticated. The service couldn’t verify your identity because authentication credentials were missing or invalid. Retrying without a valid session won’t help.
This error occurs when:
The request didn’t include the expected authentication credentials or session token.
The authentication context was removed by a gateway between your client and the service.
The session token is stale or malformed.
How to Troubleshoot
To resolve this error:
Check the detail field in the error response. It identifies which part of the authentication context was missing.
Re-authenticate to get a fresh session and try again.
If you’re connecting through a gateway, verify that authentication headers aren’t being stripped in transit.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: A2A_UNAUTHORIZED
The detail value from the response (which authentication field was missing)
PLANNER_AGENT_NOT_FOUND
The agent identifier in your request couldn’t be resolved to an agent that exists and is visible to the caller. No agent work was started. Retrying won’t help until the identifier is corrected or access is confirmed.
This error occurs when:
The agent identifier is misspelled, truncated, or belongs to a different org.
The agent was deleted or hasn’t finished being provisioned.
The agent exists but the caller doesn’t have permission to access it.
The request was sent to a different environment than the one the agent is deployed in.
How to Troubleshoot
To resolve this error:
Confirm the agent identifier exactly matches the one shown in Setup for the target org.
Verify you’re calling the environment where the agent is deployed.
Confirm the calling user or integration has access to the agent.
If the agent was created recently, allow provisioning to finish and try again.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_AGENT_NOT_FOUND
The environment you called and the approximate time of the request
PLANNER_INVALID_AGENT_DSL
The agent definition supplied with the request didn’t conform to the expected schema. The service validates the definition before starting a session and rejected it before any agent work began. Retrying won’t help until the definition is corrected.
This error occurs when:
A required field is missing from the agent definition, or is present but empty.
A field has the wrong type (for example, a string where an object is expected).
The definition was produced against a different schema version than the one the service accepts.
The definition was truncated or corrupted in transit.
How to Troubleshoot
To resolve this error:
Validate your agent definition against the published agent schema before sending it.
Check that the definition was serialized completely. Truncation often shows up as a missing trailing field.
If you generate the definition programmatically, confirm you’re targeting the current schema version.
Correct the definition and resend.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_INVALID_AGENT_DSL
The schema version your definition targets
PLANNER_INVALID_USER_INPUT_FIELDS
This error code indicates an unexpected system error and not an issue with your configuration. If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_INVALID_USER_INPUT_FIELDS
Any context that might help with the investigation, such as when the error occurred, what you or your end user were doing at the time, and whether you’re able to reproduce it
PLANNER_LLM_GATEWAY_AUTH_ERROR
This error code indicates an unexpected system error and not an issue with your configuration. If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_LLM_GATEWAY_AUTH_ERROR
Any context that might help with the investigation, such as when the error occurred, what you or your end user were doing at the time, and whether you’re able to reproduce it
PLANNER_LLM_GATEWAY_BAD_REQUEST
This error code indicates an unexpected system error and not an issue with your configuration. If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_LLM_GATEWAY_BAD_REQUEST
Any context that might help with the investigation, such as when the error occurred, what you or your end user were doing at the time, and whether you’re able to reproduce it
PLANNER_LLM_GATEWAY_EMPTY_GENERATION
The language model returned a response with no generated content. The agent couldn’t complete the turn with an empty reply, so the request failed. This is usually a temporary issue. Waiting a moment and trying again typically succeeds.
This error occurs when:
The model’s safety filters suppressed the entire generation.
The prompt left the model with no actionable instruction.
The generation stopped immediately at a stop sequence.
How to Troubleshoot
To resolve this error:
Wait at least 2 seconds and try again. Generation is non-deterministic and often succeeds on a second attempt.
If the same input consistently returns an empty response, rephrase the user message to be more specific.
Review the agent’s instructions for stop sequences or constraints that could suppress output.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_LLM_GATEWAY_EMPTY_GENERATION
Whether the same input reproduces the empty response consistently
PLANNER_LLM_GATEWAY_MALFORMED_RESPONSE
This error code indicates an unexpected system error and not an issue with your configuration. If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_LLM_GATEWAY_MALFORMED_RESPONSE
Any context that might help with the investigation, such as when the error occurred, what you or your end user were doing at the time, and whether you’re able to reproduce it
PLANNER_LLM_GATEWAY_NETWORK_ERROR
The service couldn’t establish a connection to the language model provider and the request never reached the model. This is usually a temporary issue. Waiting a moment and trying again typically succeeds.
This error occurs when:
A temporary connection failure occurred between the service and the model provider.
DNS resolution or TLS negotiation failed momentarily.
A network path or platform component was briefly unavailable.
How to Troubleshoot
To resolve this error:
Wait at least 2 seconds and try again. Most connection failures are temporary.
If failures persist for more than a few minutes, check trust.salesforce.com for known incidents.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_LLM_GATEWAY_NETWORK_ERROR
Whether the failure is intermittent or affecting all requests
PLANNER_LLM_GATEWAY_RATE_LIMIT
The request exceeded the language model capacity allocated to your org. The model provider refused the call. This is a temporary condition. Waiting before retrying typically succeeds.
This error occurs when:
A burst of concurrent conversations exhausted your org’s model quota.
An automated workload issued requests faster than the allocated rate.
Several agents in the same org competed for the same quota at the same time.
How to Troubleshoot
To resolve this error:
Wait at least 5 seconds and try again.
If you’re running automated or batch workflows, spread requests out over time instead of issuing them all at once.
If your org consistently hits this limit during normal use, contact Salesforce Customer Support to discuss your quota.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_LLM_GATEWAY_RATE_LIMIT
Your approximate request rate and how long the throttling has been occurring
PLANNER_LLM_GATEWAY_SERVICE_UNAVAILABLE
The language model provider returned a server-side error or was unreachable, so the agent couldn’t generate a response for this turn. This is usually a temporary issue. Waiting before retrying typically succeeds.
This error occurs when:
The model provider is experiencing an outage or partial degradation.
The provider is temporarily shedding load during a traffic spike.
A specific model is temporarily unavailable while capacity is rebalanced.
If your agent can use an alternative model, switching may restore service sooner.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_LLM_GATEWAY_SERVICE_UNAVAILABLE
The model your agent is configured to use and the approximate start time of the failures
PLANNER_LLM_GATEWAY_STREAM_ERROR
The model began streaming a response but the stream ended before the response was complete. Any partial content already delivered isn’t a valid answer, so the turn failed. This is usually a temporary issue. Trying again typically succeeds.
This error occurs when:
The model provider emitted an error partway through generation.
The connection dropped mid-stream.
A streamed event arrived in an unexpected format and couldn’t be interpreted.
How to Troubleshoot
To resolve this error:
Wait at least 2 seconds and try again. A fresh generation usually completes.
If interruptions recur on long responses, consider prompting for a shorter answer.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_LLM_GATEWAY_STREAM_ERROR
Whether any partial content was received before the failure
PLANNER_LLM_GATEWAY_TIMEOUT
The language model didn’t respond within the allowed time and the turn was abandoned. This is usually a temporary issue. Waiting a moment and trying again typically succeeds.
This error occurs when:
The prompt was unusually large and generation exceeded the time limit.
The model provider was slow under load.
The agent had many agent actions available, which enlarged the request.
How to Troubleshoot
To resolve this error:
Wait at least 2 seconds and try again. Most model timeouts are temporary.
If timeouts repeat, shorten the conversation input or reduce the number of agent actions available to the agent.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_LLM_GATEWAY_TIMEOUT
How many retries you attempted and whether any succeeded
PLANNER_MISSING_REQUIRED_HEADER
The request reached the service without one or more headers required to identify the org, user, or tenant. The service rejected the request before any agent work began. Retrying the same request won’t help until the missing headers are added.
This error occurs when:
A required identity header is missing from the request.
A proxy or gateway stripped the header before the request reached the service.
A header was sent with an empty value, which is treated the same as absent.
How to Troubleshoot
To resolve this error:
Compare the request headers against the required set for the endpoint you’re calling.
If you’re calling through a proxy or service mesh, confirm it forwards identity headers rather than dropping them.
Check for empty-string header values. They don’t satisfy the requirement.
Resend the request with the complete header set.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_MISSING_REQUIRED_HEADER
The list of headers your client sent (names only, no values)
PLANNER_MISSING_SESSION_CONTEXT
This error code indicates an unexpected system error and not an issue with your configuration. If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_MISSING_SESSION_CONTEXT
Any context that might help with the investigation, such as when the error occurred, what you or your end user were doing at the time, and whether you’re able to reproduce it
PLANNER_REQUEST_VALIDATION_ERROR
The request body didn’t match the schema the endpoint expects. Validation runs at the API boundary before any agent work starts. Retrying with the same body won’t help. The body must be corrected first.
This error occurs when:
A required property is missing from the request body.
A property has the wrong type, such as a string where a number or object is expected.
An enum-valued property was sent with a value outside the accepted set.
The body isn’t valid JSON or was truncated in transit.
How to Troubleshoot
To resolve this error:
Read the errors array in the response. Each entry names the specific field that failed and why.
Correct every listed field before resending. Validation reports all failures at once.
Validate your payload against the published API schema if failures persist.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_REQUEST_VALIDATION_ERROR
The field names reported in the errors array
PLANNER_SESSION_NOT_FOUND
The conversation session referenced in your request isn’t in the session store. Sessions are kept for a limited time, so this usually means the session expired, was ended, or the identifier is incorrect. Retrying against the same session won’t help. A new session must be started.
This error occurs when:
The session exceeded its retention window and was removed.
The session was ended by an earlier request.
The session identifier is misspelled or came from a different environment.
The client reused a session identifier from a previous run.
How to Troubleshoot
To resolve this error:
Start a new session and retry the turn against it.
If your client caches session identifiers, expire that cache when a session ends.
Confirm you’re sending the identifier returned by the most recent session-start call for this environment.
If the issue persists, contact Salesforce Customer Support with the following information.
The trace ID from the error response (instance field, format urn:trace:...)
The error code: PLANNER_SESSION_NOT_FOUND
How long the session had been idle before the failing request
j