Error Reporting
Errors are reported through any of the following mechanisms:
- An HTTP status code of 403, 404 or 500 with no HTTP body; relates to the whole request
- An HTTP status code of 500 or 503 with a structured error response in the HTTP body; relates to the whole request
- A nested structured error response; relates to a single operation only
The following table contains the standard returned HTTP status codes and their meaning:
Table 3.9. HTTP Status Codes
| Status Code | Meaning |
|---|---|
| 200 | Successful response |
| 403 | User and or Application Authentication credentials are insufficient (or invalid/missing) |
| 404 | Malformed URL referring to an nonexistent service endpoint or method |
| 500 | An internal error with Address Book servers |
| 503 | Service temporarily unavailable, retry later; See Retrying Requests |
Structured Error Responses
A structured error response is returned in XML or JSON format containing the following fields:
Table 3.10. Structured Error Response Fields
| Field | Meaning |
|---|---|
code
|
Numeric error code; See Address Book XML/JSON API Error Codes |
user-message
|
A message that can be shown to the user if needed, in the language of the account |
debug-message
|
An internal debug message that must not be shown to the user |
retry-after
|
[Optional] If present, indicates that the request should be retried after the specified number of seconds, due to a temporary problem |
Retrying Requests
Requests must not be automatically retried due to a failure
unless the failure response contains a retry-after field.
The Request must not be retried at a faster rate than specified in
this field.
Address Book XML/JSON API Error Codes
Error codes are signed integers (positive or negative, never zero). Not all current and future error codes are documented here. Error codes that are not documented here should be treated as "Operation failed".
Table 3.11. Address Book XML/JSON API Error Codes
| Error Code | Description | Specific user-facing message |
|---|---|---|
| 80040 | An invalid request (see debug-message for details) | |
| 80030 | Search query requests an empty field set | |
| 80020 | Syntactical error in POSTed XML or JSON | |
| 70040 | A byte sequence that is not syntactically valid utf-8 (expect error code 80020 instead) | |
| -17005 | Invalid or expired cookies (expect a 401 or 403 HTTP status instead) | |
| -17010 | Client timed out waiting for response from server | |
| -17011 | Server is down | |
| -40006 | Invalid contact criteria | |
| -40007 | Invalid display criteria | |
| -40009 | Field has too many labels (categories) | |
| -40012 | Field update's type does not match the type of the target field | |
| -40014 | Field value is empty, Field value exceeds maximum length or Field values contain invalid characters | A field is either too long or it contains invalid characters. The field "text" is either too long or it contains invalid characters.
|
| -40015 | Custom field title is missing (required for ftype Custom), Custom field title exceeds max length, Custom field title contains invalid characters
|
Invalid name for a custom field: |
| -40020 | Label name exceeds length OR Label name is empty, or Label name contains illegal characters | The name of a category cannot be empty and it cannot contain any of the following characters: slashes, @, colons, semi-colons, brackets, less-than or greater-than signs, spaces, commas, single or double quotes. |
| -40021 | Contact has no fields | |
| -40022 | Contact update has a missing or invalid contact ID | |
| -40031 | Contact has yahoo id field that is in an existing contact | You already have a contact associated with Messenger ID "value".
|
| -40032 | Label name is the same as an existing label | You already have a category named "name".
|
| -40034 | Contact has duplicate yahoo id fields | |
| -40038 | User's total number of contacts exceeds maximum | You have reached the maximum number of contacts. |
| -40039 | Number of fields on contact exceeds maximum | You have reached the maximum number of fields. |
| -40040 | User's total number of labels exceeds maximum | You have reached the maximum number of categories per field. |
| -40042 | Added or updated contact's fields are a subset of those of an existing contact, add/update rejected | |
| -40043 | Added or updated contact's fields are a superset of those of an existing contact, add/update rejected | |
| -40044 | Added or updated contact's fields are equal to those of an existing contact, add/update rejected | |
| -40045 | Added or updated contact's fields are duplicate (subset/superset/equal) of those of existing contacts, add/update rejected | |
| -40046 | Added or updated contact is missing one of the required minimum fields | A contact requires at least one of the following fields: Name, Nick name, Company, Email, Messenger ID or Phone Number. |
| -40047 | Added or updated Email field does not contain exactly one '@' character | There is a syntax error in that email address. Please enter a valid email address (in the format person@domain.com). |
| -40048 | Maximum number of labels per contact exceeded | You have reached the maximum number of categories for a contact. |
| -40049 | Maximum number of labels per Address Book exceeded | You have reached the maximum number of categories. |
| -40060 | Invalid format of a date field | |
| -40061 | Invalid GUID field | |
| -40062 | Duplicate GUID in a contact | |
| -40063 | Duplicate GUID across contacts | |
| -40064 | Invalid GUID update | |
| -40101 | Requested operation requires authentication, but no credentials sent | |
| -40102 | Signature validation failed | |
| -40103 | Cookie validation failed | |
| -40303 | Application does not have sufficient permission to perform requested operation | |
| -40304 | Writes are currently not supported in this instance | |
| -40402 | Requested contact to be updated or deleted does not exist | The contact does not exist. |
| -40403 | Requested label to be updated or deleted does not exist | The category does not exist. |
| -40404 | Requested field to be updated or deleted does not exist | Contact changes could not be saved because of a temporary problem. Please try again later. |
| -40902 | Contact update has a revision that doesn't match current contact revision | Contact changes could not be saved because of a temporary problem. Please try again later. |
| -40903 | Label update has a revision that doesn't match current label revision | Category changes could not be saved because of a temporary problem. Please try again later. |
| -40904 | Field update has a revision that doesn't match current field revision | Contact changes could not be saved because of a temporary problem. Please try again later. |
| -50302 | User is locked or being migrated, try later | There was a temporary problem accessing your address book. Please try again in 10 minutes. If you continue to see this problem, please notify customer support. Thank you.
|
Examples
The following examples assume that the Request failed because of
the "user unavailable error". This error is caused by a temporary race
condition or abusive use of the search service. This is considered to
be a temporary condition; therefore the Response contains a
retry-after field set to 600 seconds, or 10
minutes.