Uber Developers

Error Codes

Privileged and Confidential This endpoint design has been confidentially shared with you. It is still under development and is subject to change without notice. Please do not share this document or API endpoint details with anyone who is not authorized to have access. For more information read about scopes.

¶ Overview

When a tool call cannot be completed, Rides MCP returns a structured error response with a machine-readable error_code. Your agent should handle each code according to the guidance below and never expose raw error text to riders.

¶ Error Response Shape

{
  "error_code": "ERROR_CODE_LOCATION_AMBIGUOUS",
  "error_message": "The location 'Springfield' matched multiple cities.",
  "error_data": {
    "uber_deeplink": "https://m.uber.com/looking",
    "support_deeplink": "https://help.uber.com/s/article/..."
  }
}

Field	Description
`error_code`	Machine-readable identifier — use this to decide how to respond
`error_message`	Internal description — do not display directly to riders
`error_data.uber_deeplink`	Fallback URL to open Uber directly when your agent cannot complete the request
`error_data.support_deeplink`	Uber support URL for issues requiring human assistance

¶ Error Codes

Error Code	Meaning	Recommended Agent Behavior
`ERROR_CODE_INVALID_INPUT`	A required field is missing, has an invalid value, or has the wrong type	Do not retry with the same input. Ask the rider to rephrase or provide the missing detail.
`ERROR_CODE_LOCATION_AMBIGUOUS`	The location query matched multiple results and cannot be uniquely resolved	Ask the rider to clarify which location they mean. Retry with the disambiguated input. Count toward the 3-attempt limit.
`ERROR_CODE_LOCATION_NOT_FOUND`	The location could not be found	Ask for a more specific address or landmark. Do not retry with the same query.
`ERROR_CODE_LOCATION_NOT_SUPPORTED`	Rides are not available at this location	Inform the rider that Uber rides are not available for this route. Do not retry.
`ERROR_CODE_NO_PRODUCTS_AVAILABLE`	No Uber products are available from the requested origin	Inform the rider that no rides are available from that location. Do not retry immediately.
`ERROR_CODE_FARE_NOT_AVAILABLE`	A fare estimate could not be generated	Tell the rider that fare estimates are temporarily unavailable. Offer the `uber_deeplink` as a fallback.
`ERROR_CODE_USER_NOT_FOUND`	The rider’s Uber account could not be found	The rider’s account may not exist or may have been deactivated. Ask them to check their Uber account and re-link.
`ERROR_CODE_RATE_LIMITED`	The request rate is too high	Apply exponential backoff before retrying. Tell the rider estimates are temporarily unavailable rather than exposing rate-limit details.
`ERROR_CODE_SERVICE_UNAVAILABLE`	Uber services are temporarily unavailable	Inform the rider of a temporary issue and suggest retrying shortly.
`ERROR_CODE_UNAUTHORIZED`	The rider’s OAuth token is invalid or expired	Trigger the OAuth re-authorization flow so the rider can re-link their account. Do not retry with the expired token.
`ERROR_CODE_INTERNAL_ERROR`	Unexpected server-side error	Surface a generic error to the rider. Do not retry immediately.
`ERROR_CODE_UNKNOWN`	Unclassified error	Treat the same as `ERROR_CODE_INTERNAL_ERROR`.

¶ Retryable vs. Non-Retryable

Category	Error Codes
Retryable with clarification	`ERROR_CODE_LOCATION_AMBIGUOUS`
Retryable with backoff	`ERROR_CODE_RATE_LIMITED`, `ERROR_CODE_SERVICE_UNAVAILABLE`, `ERROR_CODE_FARE_NOT_AVAILABLE`
Non-retryable	`ERROR_CODE_INVALID_INPUT`, `ERROR_CODE_LOCATION_NOT_FOUND`, `ERROR_CODE_LOCATION_NOT_SUPPORTED`, `ERROR_CODE_NO_PRODUCTS_AVAILABLE`, `ERROR_CODE_USER_NOT_FOUND`
Requires re-authorization	`ERROR_CODE_UNAUTHORIZED`

¶ Iteration Limit

Do not call get_estimates_between_two_locations more than 3 times per rider request. Count every call, including retries after ERROR_CODE_LOCATION_AMBIGUOUS. After 3 attempts, stop and offer the uber_deeplink as a fallback.

Do not loop indefinitely on any error. After the iteration limit is reached, inform the rider and surface the uber_deeplink so they can continue in the Uber app.

¶ Fallback Deep Link

error_data.uber_deeplink is a last-resort fallback in any error case. Offer riders the option to open Uber directly rather than leaving them with a dead end:

Agent: "I wasn't able to get an estimate right now.
        You can open Uber directly to request your ride."
        → [uber_deeplink]