If an API request does not identify the version the partner expects, the server may apply a default, return a different contract than the client anticipates, or reject the request. The fix is not to guess a header or version number: check the partner’s current documentation, compare it with the request actually sent, and agree on what happens when a version is missing or unsupported.
Why an unspecified API version causes trouble
An API version can determine more than the shape of a response. It may define request fields, validation rules, behavior, or the resource schema that both sides rely on. If the client and server do not share an explicit selection rule, each side can make a different assumption.
As an Amazon Associate I earn from qualifying purchases.
The title does not identify the partner, endpoint, desired version, request, or incident outcome. Those details cannot be inferred from the symptom alone. For a specific integration, use the partner’s current API reference and request examples, its version-support or deprecation policy, and the actual request and response logs.
How to specify the version in a partner request
There is no universal place to put an API version. Follow the partner’s documented contract rather than choosing a mechanism based on convention.
#1 Best Overall
| Mechanism | Illustrative documented use | What to verify |
|---|---|---|
Media type in the Accept header |
Zend Server documents a vendor media type with a version parameter; PagerDuty documents an Accept-header override. Zend documentation; PagerDuty documentation. |
Use the exact media type and version syntax the partner specifies. Check whether the response’s Content-Type confirms the selected representation. |
| Custom request header | Azure API Management documents a configurable header such as Api-Version. Microsoft Learn. |
Confirm the required header name, value, and whether the partner’s endpoint actually honors it. |
| Query parameter | Azure API Management documents a query-string parameter such as api-version. Microsoft Learn. |
Check the exact parameter spelling, accepted values, and whether it belongs on the affected endpoint. |
| URL path | Google Cloud discusses a version prefix in a resource path as one design approach. Google Cloud. | Use the partner’s documented route; do not add or change a path segment by assumption. |
These are examples, not interchangeable instructions. The design choice depends on what the API already supports and documents, how clients and infrastructure handle it, what the version represents, and the cost of maintaining older versions. The cited guidance does not establish one mechanism as best for every integration.
Recovery checklist for the affected integration
- Ask the partner to confirm the contract. Identify the API version and selection mechanism for the specific endpoint and credentials in use. Ask whether a token, account setting, or other configuration supplies a default.
- Compare the documented request with the outbound request. Inspect the URL path, query string, relevant headers, SDK configuration, and any token-based default. Check what is actually transmitted, not just what the application intends to send.
- Make selection explicit when required. Configure the documented value consistently for the affected calls and keep it in integration configuration. Log the selected version where appropriate, while avoiding logging secrets or sensitive payloads.
- Read the full response. Check the status, response headers, and error body for version information, supported values, or migration guidance. A successful status alone may not establish that the intended contract was selected.
- Clarify what the version governs. Determine whether it describes the representation format, API behavior, resource schema, or another contract dimension. These meanings are related but should not be treated as interchangeable.
- Agree on edge cases and lifecycle. Confirm how the server handles an omitted version, an unsupported value, deprecation, and breaking changes; then test those cases with the partner.
What happens when a version is omitted or unsupported?
There is no universal omission behavior. Zend Server, for example, documents fallback to its oldest supported API version when its recommended Accept header is absent. Another API may choose a different default or reject the request. Microsoft’s Azure Storage guidance states: “Explicitly specify the REST protocol version to use for every request.” Microsoft Learn: Versioning best practices.
Unsupported-version behavior is also contract-specific. Zend Server documents an HTTP 406 Not Acceptable response when the server is incompatible with the requested API version, with supported version content types listed in the error data. That is a useful example of a recovery path, not a response guarantee for other APIs. Zend Technologies: Web API Versioning.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsUse the partner’s documented error contract to decide whether to select a supported version, report a configuration problem, or follow migration guidance. Do not silently retry with an arbitrary version: that can change request or response semantics without resolving the underlying compatibility issue.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Keep version changes compatible and observable
Versioning should make clear to API users whether a version concerns the representation or the underlying entity or resource. Google Cloud’s design discussion highlights this distinction and the trade-offs of different schemes. Google Cloud: API design.
For ongoing changes, Microsoft recommends backward-compatible API changes where possible and supporting older clients when introducing a breaking API version. Microsoft Learn: Web API Design Best Practices. For the integration team, that means recording the chosen version, testing against the partner’s supported contract, and tracking deprecation notices so a future default or retirement does not become another silent mismatch.
Quick Recap
Best Value
Rank #4
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →
