This section discusses the XML response that may accompany a failed API request. Please see the reference guide for more information about the HTTP response codes that the API returns.

When an API request fails, YouTube will return an HTTP 4xx or 5xx response code that generically identifies the failure as well as an XML response that provides more specific information about the error(s) that caused the failure. For each error, the XML response includes a <domain> element, <code> element and possibly a <location> element. The following subsections explain the possible values for these elements and provides a sample error response for each error. Note that error responses may contain more than one error.

This section describes the following types of errors:

1. Validation errors
2. Quota errors
3. Authentication and authorization errors
4. Service errors

Validation errors

A validation error, which is identified by a <domain> tag value of yt:validation, reports a problem related to an XML element value in a request to insert or update an entry. API functions that insert or update videos or other data can report yt:validation errors. Validation errors are typically reported with an HTTP 400 response code.

For all validation errors, the <location> tag defines the error location as an Xpath pointing to the XML tag that caused the request to fail. The Xpath location is specified relative to the <entry> tag in the request.

For validation errors, the <code> tag will contain one of the following values:

• required - This code indicates that a required field is missing or has an empty value.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:validation</domain>
      <code>required</code>
      <location type='xpath'>media:group/media:title/text()</location>
    </error>
  </errors>
  

• deprecated - This code indicates that an element's value has been deprecated and is no longer valid. For example, a video category name that has been retired may not be associated with newly added or updated videos.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:validation</domain>
      <code>deprecated</code>
      <location type='xpath'>
        media:group/media:category[@scheme='http://gdata/youtube.com/schemas/2007/categories.cat']/text()
      </location>
    </error>
  </errors>
  

• invalid_format - This code indicates that an XML element's value does not match an expected format. For example, you could receive this error if you specify invalid coordinates in the <gml:pos> tag.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:validation</domain>
      <code>invalid_format</code>
      <location type='xpath'>georss:where/gml:point/gml:pos/text()</location>
    </error>
  </errors>
  

• invalid_character - This code indicates that an XML field value contains an invalid character. For example, video titles may not contain a less than (<) character.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:validation</domain>
      <code>invalid_character</code>
      <location type='xpath'>media:group/media:title/text()</location>
    </error>
  </errors>
  

• too_long - This code indicates that an XML element's value exceeds the maximum allowable length. For example, video titles must be 60 characters or less.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:validation</domain>
      <code>too_long</code>
      <location type='xpath'>media:group/media:title/text()</location>
    </error>
  </errors>
  

Quota errors

A quota error, which is identified by a <domain> tag value of yt:quota, identifies a problem related to irregular API usage.

For quota errors, the <code> tag will contain one of the following values:

• too_many_recent_calls - This code indicates that the API servers have received too many calls from the same caller in a short amount of time. This error will not specify a location. The API response will not include a <location> tag for this type of error.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:quota</domain>
      <code>too_many_recent_calls</code>
    </error>
  </errors>
  

  If you receive this error, then your application has exceeded our current limits on API calls. We recommend that you wait a few minutes and then try your request again.

• too_many_entries - This code indicates that the user is attempting to exceed a storage limit on his account and must delete existing entries before inserting new entries. For this type of error, the <location> tag identifies the feed that caused the error.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:quota</domain>
      <code>too_many_entries</code>
      <location type='other'>https://gdata.youtube.com/feeds/users/userId/uploads</location>
    </error>
  </errors>
  

Authentication and authorization errors

An authentication error, which is identified by a <domain> tag value of yt:authentication, identifies a problem related to an improperly authorized request to execute an API function that requires user authorization. Authentication errors could be identified with HTTP 401 or 403 response codes.

Authentication errors may include a <location> element. If so, the element's value will identify the header that caused the authentication error.

For authentication errors, the <code> tag will contain one of the following values:

• InvalidToken - This code indicates that the token specified in the Authorization header is invalid.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:authentication</domain>
      <code>InvalidToken</code>
      <location type='header'>Authorization: GoogleLogin</location>
    </error>
  </errors>
  

• TokenExpired - This code indicates that the token specified in the Authorization header has expired.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:authentication</domain>
      <code>TokenExpired</code>
      <location type='header'>Authorization: GoogleLogin</location>
    </error>
  </errors>
  

Service errors

A service error, which is identified by a <domain> tag value of yt:service, identifies an authentication error that occurs when the YouTube site is undergoing temporary maintenance. This error may occur if you are trying to execute insert (POST), update (PUT) or delete (DELETE) operations. This error will not occur if you are only executing read (GET) operations.

For service errors, the <code> tag will contain the following value:

• disabled_in_maintenance_mode - This code indicates that POST, PUT and DELETE operations cannot be executed because the site is temporarily in maintenance mode. If you receive this error, wait a few minutes and try your request again.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:service</domain>
      <code>disabled_in_maintenance_mode</code>
    </error>
  </errors>
  

• youtube_signup_required - This code is returned in API version 2.1 when a user with an unlinked Google Account submits an API request that requires the authenticated user to have a YouTube channel. If you receive this error, your application should indicate that the requested operation requires the user to have a YouTube channel and should display an option to link to https://www.youtube.com/create_channel. That page will let the user associate her Google Account with a YouTube channel. If you are building a mobile application, you can bypass a redirect by presenting a link to https://m.youtube.com/create_channel instead.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:service</domain>
      <code>youtube_signup_required</code>
    </error>
  </errors>
  

Last updated August 17, 2012.