Errors

Ampache's API errors are modelled on the HTTP status codes. All errors are returned as an XML/JSON document with a US English message string; services should rely on the numeric code, not the message text.

The structured error format below applies to API versions 5, 6 and 8 (8 is the current default). It expands on the information available to the user/client/application that caused the error.

A structured error has the following parts:

• errorCode: numeric code
• errorAction: method that caused the error
• errorType: further information such as the type of data missing or access level required
• errorMessage: error message (US English string, Ampache 6.4.0+)

NOTE Prior to Ampache 6.4.0 the API errorMessage text was translated into the server locale. Current versions do not translate it.

HTTP status codes and API versions

How an error reaches the client depends on the API version:

• API 3, 4, 5 and 6 always return HTTP 200, carrying the failure only in the response body.
• API 8 sets a real HTTP status code for the error (mapped from the error code, see the list below) and returns HTTP 404 for an empty result. The body still carries the same error object.

Only the errorCode value is portable across versions — do not rely on the HTTP status unless you are pinned to API8.

Rules Regarding errors

• XML and JSON errors are always in an 'error' object.
• Errors will always provide a code
• The data names used in the error must use names that don't conflict with other data objects
• errorAction will return the method used that caused the error
• Use errorType 'system' for things users can't change / server config
• Use errorType 'account' for user issues (password, perms, auth, etc)
• All other errorTypes should return the parameter name that caused the error. (type, filter, email, etc)
• errorMessage is written in US English only

Error Codes

All error codes are accompanied by a string value for the error and derived from the HTTP/1.1 Status Codes

To separate Ampache from the http codes it's been decided to prefix our codes with 47 to allow clear differentiation. The HTTP status shown for each code is the one API8 sets (API 3-6 always answer HTTP 200; see above).

• 4700 Access Control not Enabled (API8 HTTP 403)
  • The API is disabled. Enable 'access_control' in your config
• 4701 Received Invalid Handshake (API8 HTTP 401)
  • This is a temporary error, this means no valid session was passed or the handshake failed
• 4702 Generic Error (API8 HTTP 500)
  • An unexpected server-side error. Check the server debug logs for details
• 4703 Access Denied (API8 HTTP 403)
  • The requested method is not available
  • You can check the error message for details about which feature is disabled
• 4704 Not Found (API8 HTTP 404)
  • The API could not find the requested object
• 4705 Missing (API8 HTTP 400)
  • This is a fatal error, the service requested a method that the API does not implement
• 4706 Depreciated (API8 HTTP 410)
  • This is a fatal error, the method requested is no longer available
• 4710 Bad Request (API8 HTTP 400)
  • Used when you have specified a valid method but something about the input is incorrect, invalid or missing
  • You can check the error message for details, but do not re-attempt the exact same request
• 4742 Failed Access Check (API8 HTTP 403)
  • Access denied to the requested object or function for this user

Error Types

There are three error types; two are static 'account' and 'system'

Account errors are things that your user can't do. Either the permission level or something with the session is incorrect.

System errors tell you whether a system feature is disabled or something else has failed on the server. Check the debug logs for further information.

Everything else will be a parameter from the call that caused your error. Maybe the email you used was malformed or the song you looked for doesn't exist?

Example Error messages

Error 4700: Access Control not Enabled

Example XML

<?xml version="1.0" encoding="UTF-8" ?>
<root>
    <error errorCode="4700">
        <errorAction><![CDATA[handshake]]></errorAction>
        <errorType><![CDATA[system]]></errorType>
        <errorMessage><![CDATA[Access Denied]]></errorMessage>
    </error>
</root>

Example JSON

{
    "error": {
        "errorCode": "4700",
        "errorAction": "handshake",
        "errorType": "system",
        "errorMessage": "Access Denied"
    }
}

Error 4701: Received Invalid Handshake

Example XML

<?xml version="1.0" encoding="UTF-8" ?>
<root>
    <error errorCode="4701">
        <errorAction><![CDATA[playlist_create]]></errorAction>
        <errorType><![CDATA[account]]></errorType>
        <errorMessage><![CDATA[Session Expired]]></errorMessage>
    </error>
</root>

Example JSON

{
    "error": {
        "errorCode": "4701",
        "errorAction": "playlist_create",
        "errorType": "account",
        "errorMessage": "Session Expired"
    }
}

Error 4703: Missing Feature

Example XML

<?xml version="1.0" encoding="UTF-8" ?>
<root>
    <error errorCode="4703">
        <errorAction><![CDATA[podcasts]]></errorAction>
        <errorType><![CDATA[system]]></errorType>
        <errorMessage><![CDATA[Enable: podcast]]></errorMessage>
    </error>
</root>

Example JSON

{
    "error": {
        "errorCode": "4703",
        "errorAction": "podcasts",
        "errorType": "system",
        "errorMessage": "Enable: podcast"
    }
}

Error 4704: Not Found

Example XML

<?xml version="1.0" encoding="UTF-8" ?>
<root>
    <error errorCode="4704">
        <errorAction><![CDATA[scrobble]]></errorAction>
        <errorType><![CDATA[song]]></errorType>
        <errorMessage><![CDATA[Not Found]]></errorMessage>
    </error>
</root>

Example JSON

{
    "error": {
        "errorCode": "4704",
        "errorAction": "scrobble",
        "errorType": "song",
        "errorMessage": "Not Found"
    }
}

Error 4705: Missing Method

Example XML

<?xml version="1.0" encoding="UTF-8" ?>
<root>
    <error errorCode="4705">
        <errorAction><![CDATA[plafgfylist_create]]></errorAction>
        <errorType><![CDATA[system]]></errorType>
        <errorMessage><![CDATA[Invalid Request]]></errorMessage>
    </error>
</root>

Example JSON

{
    "error": {
        "errorCode": "4705",
        "errorAction": "plafgfylist_create",
        "errorType": "system",
        "errorMessage": "Invalid Request"
    }
}

Error 4706: Depreciated Method

Example XML

<?xml version="1.0" encoding="UTF-8" ?>
<root>
    <error errorCode="4706">
        <errorAction><![CDATA[tag_songs]]></errorAction>
        <errorType><![CDATA[removed]]></errorType>
        <errorMessage><![CDATA[Depreciated]]></errorMessage>
    </error>
</root>

Example JSON

{
    "error": {
        "errorCode": "4706",
        "errorAction": "tag_songs",
        "errorType": "removed",
        "errorMessage": "Depreciated"
    }
}

Error 4710: Bad Request

Example XML

<?xml version="1.0" encoding="UTF-8" ?>
<root>
    <error errorCode="4710">
        <errorAction>user_create</errorAction>
        <errorType>username</errorType>
        <errorMessage>Bad Request: temp_user</errorMessage>
    </error>
</root>

Example JSON

{
    "error": {
        "errorCode": "4710",
        "errorAction": "user_create",
        "errorType": "username",
        "errorMessage": "Bad Request: temp_user"
    }
}

Error 4742: Failed Access Check

Example XML

<?xml version="1.0" encoding="UTF-8" ?>
<root>
    <error errorCode="4742">
        <errorAction><![CDATA[playlist_delete]]></errorAction>
        <errorType><![CDATA[account]]></errorType>
        <errorMessage><![CDATA[Require: 100]]></errorMessage>
    </error>
</root>

Example JSON

{
    "error": {
        "errorCode": "4742",
        "errorAction": "playlist_delete",
        "errorType": "account",
        "errorMessage": "Require: 100"
    }
}