Error messages and trouble-shooting

The following table displays the commonly encountered BOSS API error messages and any description or resolution for that error message. Yahoo hopes using this table helps you trouble-shoot your BOSS API implementation before you request technical support.

If you have any issues not listed below please join the Yahoo Groups BOSS forum:

HTTP status codes Problem Description & Resolution
400 bad request Un-escaped reserved characters. Something else wrong with request (API). Check your BOSS API parameters.
401 Invalid consumer key in a request
403 invalid AppID error, access denied, Access is forbidden Possible production code errors and not client-side errors. Please retry your API query.
406 not acceptable Accept-encoding setting must be set to ‘gzip’. Keep-alive must be turned off (cannot reuse port connections).
407 Proxy authentication required. Yahoo BOSS API does not use proxy authentication. Please check your systems.
408 Your request has timed out. Please try your request again. If this problem persists, please send a message to the BOSS Yahoo Groups forum.
414 Request-URL Too Large. URL too long for the system to process.
500 Internal server error Received when server problems occur. Please retry your query. Single letter query may also cause this error to be displayed.
500 Internal server error | Received when server problems occur. Please retry your query. Single letter query may also cause this error to be displayed. |
504 Caused by server problems in Yahoo services. Please retry your query.
No result for common queries User may be sending a spelling query instead of a web query. Please check/verify that you have chosen the correct service in your API.
Wrong language returned Please set both the region and language in your API query.

Reserved Characters and Escape Values

Use the following characters in URLs only in syntactically required locations. To use in argument values, they must be escaped.

Reserved character Escape value
slash (/) %2F
question mark (?) %3F
ampersand (&) %26
semicolon (;) %3B
colon (:) %3A
commercial at sign (@) %40
comma (,) %2C
dollar sign ($) %24
equals sign (=) %3D
space ( ) %20
percent sign (%) %25
quotation marks (”) %22
plus sign (+) %2B
hash (#) %23
asterisk (*) %2A
less-than sign (<) %3C
greater-than sign (>) %3E
left brace ({) %7B
right brace (}) %7D
vertical bar (|) %7C
left square bracket ([) %5B
right square bracket (]) %5D
circumflex (^) %5E
backslash (\) %5C
accent grave (`) %60
left parenthesis (() %28
right parenthesis ()) %29

If a URL contains invalid characters, BOSS API returns a Bad Request response with a status code of 400.


Some of the BOSS API examples in this document contain reserved characters that need to be escaped. However, for legibility the examples eliminate the escape values. Therefore, if you use these examples verbatim to test queries, they will not work.

Supported Regions and Languages

The following supported regions and languages lists are used only for each identified BOSS API service. These market parameters cannot be applied to other BOSS API services.

Regions and Languages - BOSS API Services

Country/Language Market Web Limitedweb Image News Also Try Blog Spelling
Argentina - Spanish es-ar X X X X X   X
Austria – German de-at X X X X     X
Australia – English en-au X X X X X   X
Belgium - Dutch nl-be X   X        
Brazil – Portuguese pt-br X X X X     X
Bulgaria - Bulgarian bg-bg X   X        
Canada - English en-ca X X X X X   X
Canada - French fr-ca X X X X X   X
Chile - Spanish es-cl X X X X     X
Colombia - Spanish es-co X X X X     X
Croatia - Croatian hr-hr X   X        
Czech Republic cs-cz X X X X      
Denmark – Danish da-dk X X X X      
Estonia - Estonian et-ee X   X        
Finland – Finnish fi-fi X X X X     X
France - French fr-fr X X X X X   X
Germany - German de-de X X X X X   X
Greece - Greek el-gr X X X        
Hong Kong* – Simplified ChineseX zh-hant-hk X X X X X X X
Hungary - Hungarian hu-hu X X X X      
Indonesia - English id-en X X X X X    
Indonesia - Indonesian id-id X X X X X    
India – English en-in X X X X X   X
Ireland - English en-ie X   X       X
Israel - Hebrew he-il X X X X      
Italy - Italian it-it X X X X X   X
Japan – Japanese ja-jp X X X X     X
Korea - Korean ko-kr X X X X   X X
Latvia - Latvian lv-lv X   X        
Lithuania - Lithuanian lt-lt X   X        
Malaysia - English en-my X X X X      
Malaysia– Malaysian ms-my X X X X X    
Mexico- Spanish es-mx X X X X X   X
Netherlands - Dutch nl-nl X X X X      
New Zealand - English en-nz X X X X X   X
Norway – Norwegian no-no X X X X      
Peru – Spanish es-pe X X X X     X
Philippines** – Filipino tl-ph X X X X X    
Philippines - English en-ph X X X X X    
Poland - Polish pl-pl X   X        
Romania - Romanian ro-ro X X X X      
Russia Federation – Russian ru-ru X X X X      
Saudi Arabia - Arabic ar-xa X   X        
Singapore - English en-sg X X X X X   X
Slovakia - Slovak sk-sk X   X        
Slovenia - Slovenian sl-si X   X        
Spain – Catalan ca-es X X X X      
Spain – Spanish es-es X X X X X X X
Sweden – Swedish sv-se X X X X      
Switzerland - French fr-ch X X X X     X
Switzerland - German de-ch X X X X     X
Switzerland - Italian it-ch X X X X     X
Thailand - Thai th-th X X X X X    
Taiwan* – Traditional Chinese zh-hant-tw X X X X X X X
Turkey – Turkish tr-tr X X X X      
United Kingdom - English en-gb X X X X X   X
United States - English en-us X X X X X X X
United States - Spanish es-us X X X X X   X
Venezuela - Spanish es-ve             X
Vietnam – Vietnamese vi-vn X X X X X X X

Region/Language example usage:{service}?q={keyword}&market=fr-fr&format=xml. For more information see the Universal Yahoo BOSS API Arguments.

* BOSS API results for the Hong Kong and Taiwan markets may differ from the Y! Hong Kong and Y! Taiwan search properties.

** News does not support ph-tl at this time.

Improving Performance Using BOSS

Yahoo BOSS is a critical part of many online sites and it is important that these sites can maximize the performance benefits that BOSS can provide site owners. We have provided you a helpful guide of suggestions for using BOSS.

1. Using GZIP when Retrieving Results Yahoo BOSS supports the response to be zipped when sending over the network. Enabling gzip encoding ensures that the data transmitted is reduced in size and hence transferred faster.

To enable gzip in PHP here is a snippet of code. Please refer to the documentation of the programming language of your choice if you have further questions.

curl_setopt($ch,CURLOPT_ENCODING , "gzip");

2. Keep Alive Header Yahoo BOSS supports persistent HTTP connections via a Keep Alive Header. Adding this header to your BOSS request ensures that you re-use an existing connection and hence reduce handshake time significantly.

You can use Keep Alive connections by turning on the Keep Alive header in your request. Here is a snippet of code using PHP.

$curl = curl_init();

// Add more code here for conection initialization
$header[] = "Connection: keep-alive";
$header[] = "Keep-Alive: 300";
// Set more header values here

// Add more code here for oAuth authorization

$url = "BOSS URL"; Add your BOSS URL here
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
$rsp = curl_exec($ch);
$results = json_decode($rsp);


It is not recommended using Persistent HTTP with SSL turned on.

3. Controlling the Number of Results Returned Yahoo BOSS Search by default returns as many as 50 results per query for services such as web search. Most sites however do not need such a large set of results. The performance of API is driven by the number of results requested. If your site only has a need for 10 results per query, then make sure to only request that set. The response will be faster. You can control the number of results returned using the count parameter.

Here is a sample call that shows how to use it using a simple web search call:

This query returns only 10 results for dvd in JSON format.