.. error-codes.rst
   Copyright (c) 2016 LMG. All rights reserved
   This software is the confidential and proprietary information of LMG ("Confidential Information").
   You must not disclose such Confidential Information.
   Created by usischev

.. _error-codes-label:

Error Codes
-----------

Body of every JSON response includes ``status`` field. Its value is ``success`` for successfully carried out requests
or ``error`` if any error occurred. Each error response has a respective HTTP status code and the following JSON fields:

``error_code``
    Error code, see descriptions grouped by HTTP status code below

``error_id``
    Unique ID of error response for reference

``messages``
    Array or object of error messages. If it is an object, its field names correspond to request JSON field names.

HTTP 401 Unauthorized
^^^^^^^^^^^^^^^^^^^^^

**auth.apikey.missing**
    Request does not have ``X-Api-Key`` header which must contain API key of the client application.

**auth.apikey.invalid**
    API key supplied in ``X-Api-Key`` request header is invalid.

**auth.header.missing**
    Request does not have ``Authorization`` header which must contain authentication token or request signature.

**auth.header.invalid**
    ``Authorization`` request header has invalid format. ``Bearer <auth_token>`` or ``Signature <signature>`` format
    is required.

**auth.token.expired**
    ``Authorization`` request header or ``token`` request field contains an expired authentication token.

**auth.token.invalid**
    ``Authorization`` request header or ``token`` request field contains an invalid authentication token.

**auth.signature.invalid**
    ``Authorization`` request header contains an invalid request signature.

**auth.signature.expired**
    ``Authorization`` request header contains an expired request signature.

**auth.captcha.missing**
    Request must include ``captcha_response`` field which is missing.

**auth.captcha.invalid**
    ``captcha_response`` request field contains invalid captcha response.

**auth.session.invalid**
    User session state is invalid for this request.

**auth.password.invalid**
    Request supplied invalid current user password.

**auth.otp.invalid**
    ``otp`` request field contains invalid one-time password.

**auth.backupcode.invalid**
    ``backup_code`` request field contains invalid one-time backup code.

**auth.memorable.invalid**
    ``memorable_letters`` request field contains invalid letters of user's memorable words.

**auth.controlanswer.invalid**
    ``control_answer`` request field contains invalid answer to control question for recovery.

**auth.disclaimer.invalid**
    ``accept_disclaimers`` request field is missing a legal disclaimer required to be accepted by user.

**auth.oauth.failed**
    Verification with OAuth provider failed.

HTTP 403 Forbidden
^^^^^^^^^^^^^^^^^^

**auth.user.restricted**
    User profile is currently restricted from using any API endpoints requiring authorization.

**auth.user.closed**
    User profile is closed and restricted from using any API endpoints requiring authorization.

**auth.user.denied**
    Service is administratively denied for user profile.

**auth.restricted**
    Request cannot be carried out with presented data due to access restrictions.

**recovery.question.notset**
    Access recovery by security question requested for user that has no control question set.

**recovery.phone.notset**
    Access recovery by phone requested for user that has no primary phone set.

**recovery.email.notset**
    Access recovery by email requested for user that has no primary email set.

**recovery.method.restricted**
    Requested access recovery method is restricted.

**profile.identifier.used**
    Profile primary identifier (primary phone or primary email) supplied in request is already used.

**profile.identifier.invalid**
    Profile primary identifier (primary phone or primary email) supplied in request is invalid.

**oauth.identifier.used**
    OAuth user identifier supplied for entry is already used by entry of the same client.

**object.limit.exceeded**
    Attempt to add more objects than maximum limit.

**critical.auth.required**
    To carry out this request, critical change authentication must be performed.

    If response field ``critical_auth_method`` is set to ``password``, client application is supposed to repeat request
    including ``password`` field containing valid user password.

    If response field ``critical_auth_method`` is set to ``otp``, an SMS with one-time password has been sent to user
    phone. Client application is supposed to repeat request including ``otp`` field containing valid OTP.

**member.data.invalid**
    Member data supplied for member entry validation is invalid.

**search.type.restricted**
    Requested object type for search is restricted.

HTTP 404 Not Found
^^^^^^^^^^^^^^^^^^

**auth.oauth.notfound**
    OAuth verification returned user id that is not found.

**auth.loginid.notfound**
    Request ``login_id`` field contains user login ID that is not found.

**object.id.notfound**
    Requested object id is not found.

HTTP 422 Unprocessable Entity
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**request.validation.failed**
    Request data either is invalid JSON or failed field value validation.