Skip to content
Guide

ACE validation errors explained: what the Partner Central Selling API is telling you

The Partner Central Selling API refuses a bad request with a named exception and, for validation failures, a list of fields and codes. This guide decodes the errors developers and connector users meet most, the AWS rules behind them, and the fix for each.

9 min readUpdated By the HabileLabs CoSell team

When you create, update or submit ACE opportunities through the AWS Partner Central Selling API, directly or through a connector, AWS refuses a bad request with an exception. This guide explains what the errors look like, the rules behind them, and how to fix the common ones. Rules are as AWS documents them as of November 2026. Where a rule comes from what the CoSell team saw in production or Sandbox calls instead, the guide says so. If AWS accepted the opportunity but its review came back as Action Required, see what Action Required means and how to fix it.

What an error looks like

The Selling API returns these exceptions on its opportunity actions:

  • ValidationException: the input breaks a format constraint or a business rule. It carries a Reason and an ErrorList.
  • ConflictException: the request conflicts with the record's current state. Fetch it again and retry.
  • ResourceNotFoundException: the record does not exist, or your credentials cannot see it.
  • AccessDeniedException: your identity lacks permission. It carries a Reason.
  • ThrottlingException: you sent too many requests.
  • ServiceQuotaExceededException: the request would exceed a quota. StartEngagementFromOpportunityTask can return it.
  • InternalServerException: usually transient. Retry after a short delay.

AWS's action pages list HTTP 400 for every one of these except InternalServerException, which is 500. Branch on the exception name, not the status code.

Inside a ValidationException

Reason says which kind of check failed:

  • REQUEST_VALIDATION_FAILED: the request itself is malformed, with missing required fields, wrong data types or bad string formats.
  • BUSINESS_VALIDATION_FAILED: the request is well formed but breaks a Partner Central business rule.

ErrorList holds one entry per problem. Each has a Message and a Code, and usually a FieldName. The codes are:

  • REQUIRED_FIELD_MISSING: a required field is absent.
  • INVALID_ENUM_VALUE: the value is not one AWS accepts for that field.
  • INVALID_STRING_FORMAT: the string does not match the expected format, such as an email address or a date.
  • INVALID_VALUE: the value is outside the allowed range or set.
  • TOO_MANY_VALUES and NOT_ENOUGH_VALUES: a list has more or fewer entries than allowed.
  • ACTION_NOT_PERMITTED: the change is not allowed in the record's current state, or with your permissions.
  • DUPLICATE_KEY_VALUE: a value that must be unique already exists.

AWS also lists INVALID_RESOURCE_STATE and VALUE_OUT_OF_RANGE as valid codes, without a description. In CoSell's calls, field names in messages came back in lower camel case, such as customer.account.address.stateOrRegion, while request fields are written Customer.Account.Address.StateOrRegion. Compare them without regard to case.

Submission errors can arrive as a failed task

StartEngagementFromOpportunityTask is asynchronous. It runs several steps, including SubmitOpportunity. A refusal can come back as TaskStatus FAILED with a ReasonCode, such as OpportunityValidationFailed, OpportunitySubmissionFailed or RequestThrottled, and a Message explaining the failure, rather than as an exception. Read the task result, or look it up with ListEngagementFromOpportunityTasks.

The errors people hit most

Error or messageWhat it meansHow to fix
REQUIRED_FIELD_MISSING on fields you did not changeUpdateOpportunity replaces the whole record. Any field you leave out becomes null.Call GetOpportunity, change only what you mean to, and send the full record.
REQUIRED_FIELD_MISSING on customer.account.address.stateOrRegionThe customer is in the US and has no state. CoSell saw this at submission.Send a state name from AWS's list, such as California.
Submission refused for a missing delivery model, sales activities or use caseThe API marks these optional, but CoSell has seen AWS refuse submission without them.Fill Project.DeliveryModels, Project.SalesActivities and Project.CustomerUseCase before you submit.
INVALID_ENUM_VALUEA value is not on AWS's list, for example the industry, country, use case or delivery model.Send the exact value AWS lists, with the same spelling, spacing and case.
INVALID_STRING_FORMATA string breaks AWS's pattern, for example an email address or a date.Use lower-case email of at most 80 characters, phone as + and digits, and dates as YYYY-MM-DD.
ACTION_NOT_PERMITTED on country, postal code or websiteThe opportunity is approved and AWS has locked these fields. CoSell has seen this.Leave locked fields unchanged and keep AWS's values in the payload.
lifeCycle.stage is not editable post launchThe opportunity is Launched, so its stage can no longer change. CoSell also saw this for the city.Stop sending stage changes for launched opportunities.
You can not update the stage when Opportunity status is Pending SubmissionAWS refused a stage change before submission. CoSell saw this in the Sandbox.Set the stage when you create the opportunity.
Update refused while Submitted or In reviewAWS blocks all updates during its review.Wait for the review result, then update.
ConflictException on UpdateOpportunityYour LastModifiedDate does not match AWS's copy.Fetch the record again, reapply your change, and retry.
Conflicting client token submitted for a new request body.You reused a ClientToken with a different CreateOpportunity request.Use a new token for a new request. Reuse a token only to retry the same request.
ResourceNotFoundExceptionThe record does not exist, or these credentials cannot see it.Check the O-prefixed ID, the Catalog value and the credentials.
AccessDeniedExceptionThe IAM identity lacks the partnercentral: action, or a condition such as the catalog blocks it.Add the action to the identity's policy.
ThrottlingExceptionYou are over the request rate or the daily quota.Back off exponentially and retry.

Rules that make a field required or refuse a value

Required at submission, not at creation

CreateOpportunity marks most fields optional, but AWS checks more at submission. Before StartEngagementFromOpportunityTask, AWS requires one to ten Partner Solutions, AWS Marketplace solutions or AWS Marketplace products on the opportunity. Each must be in Public or Limited status; AWS rejects draft or inactive entities. You attach them only with AssociateOpportunity. CreateOpportunity and UpdateOpportunity cannot set RelatedEntityIdentifiers.

Since 1 July 2026, moving an opportunity to Committed or Launched also requires an associated AWS Marketplace solution, AWS Marketplace product or Partner Solution. The console's Other option, described in Project.OtherSolutionDescription, is none of these, so on its own it does not meet the rule as AWS words it.

Values that need a companion field

  • Industry Other needs Customer.Account.OtherIndustry, up to 255 characters.
  • Project.OtherCompetitorNames is allowed only when Project.CompetitorName is *Other.
  • Project.OtherSolutionDescription describes your offer when the solution is Other.
  • NationalSecurity applies only when the industry is Government. The Partner Central form asks for it in that case.
  • When you choose co-sell, the Partner Central form asks for at least one value in PrimaryNeedsFromAws.

Address and contact rules

  • CountryCode is a two-letter code from AWS's list, such as US or IN.
  • StateOrRegion takes names from AWS's list, which holds US states and territories. A US customer needs one.
  • PostalCode is up to 20 characters. The Partner Central form requires it.
  • WebsiteUrl is 4 to 255 characters, and required except for national security opportunities.
  • Duns, if you send it, is nine digits.
  • A contact Email must be lower case throughout and at most 80 characters. Lower-case addresses before sending.
  • A contact Phone is + followed by up to 15 digits.

Expected spend

  • Frequency is Monthly.
  • TargetCompany is AWS. Self is accepted only when Project.ExpectedContractDuration is present.
  • AWS's description says CurrencyCode accepts USD and EUR, although the list of values is longer. The AWS European Sovereign Cloud partition (aws-eusc) requires EUR.
  • Amount is digits with up to two decimals. No thousands separators and no currency symbols.
  • EstimationUrl, if present, must be an AWS Pricing Calculator estimate link.
  • ExpectedCustomerSpend takes at most 10 entries.

Text fields and picklists

  • Project.CustomerBusinessProblem is 20 to 2,000 characters.
  • LifeCycle.NextSteps is up to 255 characters, and PartnerOpportunityIdentifier up to 64.
  • LifeCycle.TargetCloseDate must not be in the past.
  • In the AWS catalog, Origin must be Partner Referral.
  • Copy use case values from AWS's current list. AWS's API reference writes some without spaces around the slash, such as Migration/Database Migration. CoSell found that ACE takes the spaced form, Migration / Database Migration, as Partner Central's own list writes it (Sandbox, 1 November 2026).

Locked fields and stage rules

  • Submitted and In review: nothing can change.
  • Action Required: only the customer address, website, target close date, expected spend, business problem and PartnerOpportunityIdentifier.
  • Approved: everything except country, postal code, industry, website, business problem, PartnerOpportunityIdentifier and title, plus any business rule AWS applies. CoSell has also seen AWS refuse a company name change.
  • Launched: AWS publishes no list. CoSell has seen AWS refuse changes to the stage and the city.
  • Stage: AWS takes submissions from Qualified onwards, and not for an opportunity already closed as lost.

UpdateOpportunity needs the full record. If you build it from a GetOpportunity response, AWS's Sandbox guide says to rename Id to Identifier and remove CreatedDate, OpportunityTeam and RelatedEntityIdentifiers. Keep LifeCycle.ReviewStatus as AWS returned it. In CoSell's Sandbox tests, leaving it out blanked the status, and the opportunity could no longer be submitted.

Catalogs, identifiers and idempotency

  • Catalog is AWS for real opportunities and Sandbox for testing without touching live data. In the Sandbox, you simulate AWS's review by setting LifeCycle.ReviewStatus to Approved or Action Required yourself.
  • The Selling API endpoint is in US East (N. Virginia): partnercentral-selling.us-east-1.api.aws.
  • Opportunity IDs are O followed by digits. Engagement IDs start eng- and engagement invitation IDs engi-.
  • ClientToken is required on CreateOpportunity and on StartEngagementFromOpportunityTask. AWS recommends a UUID, unique to the request and unchanged across its retries.
  • CoSell found that a submission reusing the token of an earlier, refused attempt can repeat that refusal even after you fix the data. Derive the token from the opportunity's current version.
  • PartnerOpportunityIdentifier holds your CRM's record ID. AWS locks it after approval.

Throttling and retries

AWS's quotas apply per partner account:

  • write actions such as CreateOpportunity, UpdateOpportunity, AssociateOpportunity and StartEngagementFromOpportunityTask: 1 request a second and 10,000 in a rolling 24 hours;
  • read actions such as GetOpportunity, ListOpportunities and GetAwsOpportunitySummary: 10 a second and 100,000 in 24 hours.

Over a limit, AWS returns ThrottlingException, and the AWS SDKs retry it automatically. AWS recommends exponential backoff; add random jitter so parallel workers do not retry in step. Retry InternalServerException after a short delay. Never retry ValidationException or AccessDeniedException unchanged, and fetch the record again before retrying a ConflictException. To save read quota, react to Amazon EventBridge events, or poll ListOpportunities with the AfterLastModifiedDate filter. Request higher limits in Service Quotas.

Where CoSell fits

CoSell connects Salesforce, HubSpot, Microsoft Dynamics 365, Zoho CRM or LeadSquared, or CoSell's built-in CRM, to Partner Central through the Selling API. It checks each deal against AWS's rules inside your CRM workflow before submission and names the field to fix; AWS's own Partner Central agent can also check drafts in the console. After submission, CoSell shows AWS's review status and comments on the deal, keeps an error inbox with retry, and leaves out fields AWS has locked instead of failing the whole update. It runs hosted by HabileLabs or in your own AWS account, from USD 10 a month on AWS Marketplace; the offer is currently for AWS accounts in India. See features and pricing.

Sources

More guides

All guides

Available in AWS Marketplace

Try CoSell free for 30 days

Start the free trial on AWS Marketplace with your AWS account. Your workspace is ready in minutes, and you connect your CRM yourself.