Error codes

This document aggregates all error codes that AirDroid Business tools may return, along with handling recommendations.

1. Error Code Overview

AirDroid Business uses a three-tier StatusCode strategy. All tools return one of the following three values:

Key Rule: StatusCode == 200 does NOT always mean success. You must check ErrorMessage — empty string means success, non-empty means business error (including upstream HTTP errors like 401/403/404).

2. Detailed Error Descriptions

2.1 StatusCode: -1 — Parameter Validation Error

Description: Local parameter validation failed before sending the request to the API. The HTTP request was never made.

Common Causes (refer to actual ErrorMessage):

Example Response:

{
  "StatusCode": -1,
  "ErrorMessage": "device_id is required"
}

Agent Self-Healing Strategy:

• Do NOT retry — fix the parameters and call again
• Parse ErrorMessage for hints on which parameter is wrong

2.2 StatusCode: 200 — Success or Business Error

Description: The HTTP request completed. Check ErrorMessage to determine the actual result.

Success Criteria: StatusCode == 200 AND ErrorMessage == ""

Example Success Response:

{
  "StatusCode": 200,
  "ErrorMessage": "",
  "Devices": [...]
}

Example Business Error Responses:

When the upstream API returns an error, StatusCode remains 200 but ErrorMessage contains the error detail:

{
  "StatusCode": 200,
  "ErrorMessage": "API returned error: Device not found"
}

{
  "StatusCode": 200,
  "ErrorMessage": "API returned HTTP 401: {\"code\":0,\"msg\":\"Unauthorized\"}"
}

{
  "StatusCode": 200,
  "ErrorMessage": "API returned HTTP 403: {\"code\":0,\"msg\":\"Permission denied\"}"
}

Common ErrorMessage Patterns:

Agent Self-Healing Strategy:

• If ErrorMessage is empty → success, process the result
• If ErrorMessage contains HTTP 401 → refresh credentials and retry
• If ErrorMessage contains HTTP 429 → wait 60 seconds and retry
• Otherwise → do NOT retry, parse the message and take corrective action

2.3 StatusCode: 500 — Network / Request Exception

Description: A network-level or system-level error occurred. The request may not have reached the server, or the response could not be parsed.

Common Causes:

Example Responses:

{
  "StatusCode": 500,
  "ErrorMessage": "Request timeout after 60 seconds."
}

{
  "StatusCode": 500,
  "ErrorMessage": "Request error: ConnectionError"
}

{
  "StatusCode": 500,
  "ErrorMessage": "Unexpected error: ..."
}

Agent Self-Healing Strategy:

• May retry 1-2 times (5-second interval)
• If failure persists, log the error and stop retrying
• For timeout errors, try reducing request scope (e.g., fewer SelectedColumns, smaller PageSize)

3. Agent Self-Healing Decision Table

4. Error Handling Best Practices

4.1 Error Response Parsing

def handle_response(response):
    status_code = response.get("StatusCode", 500)
    error_msg = response.get("ErrorMessage", "")

    if status_code == 200 and not error_msg:
        return response

    if status_code == -1:
        raise ValidationError(error_msg)

    if status_code == 500:
        # Network error — may retry 1-2 times
        raise NetworkError(error_msg)

    if status_code == 200 and error_msg:
        if "HTTP 401" in error_msg:
            # Refresh token and retry
            pass
        elif "HTTP 429" in error_msg:
            # Wait and retry
            pass
        else:
            # Business error — do not retry
            raise BusinessError(error_msg)

4.2 Logging Recommendations

When an error occurs, log the following information:

• StatusCode — error code (-1, 200, or 500)
• ErrorMessage — error description
• Request parameters (sanitized)
• Timestamp
• Action name

5. Operation-Specific Error Codes

5.1 Async Operation Progress Values

For async operations (Reboot, Lock, Lost Mode, etc.), use Get an Activity Log to track status:

5.2 Common FailReason Values

6. FAQ

Q1: Why is my Keyword filter not working?

Possible causes:

1. Used an unsupported filter field (e.g., group_id)
2. Field name misspelled
3. Value format incorrect (e.g., online should use "Online" not 1)
4. Keyword passed as string instead of object

Solution:

Refer to Field Reference - Keyword Filtering Fields to confirm supported fields and correct value formats.

Q2: Device query returns stale data?

Cause: Device status may be cached.

Solution:

1. Call Get Device Info Push first to refresh device status
2. Then call Get All Devices to get updated data

Q3: StatusCode is 200 but operation failed?

Cause: StatusCode == 200 only means the HTTP request completed. The upstream API may have returned an error.

Solution:

Always check ErrorMessage. If it's non-empty, the operation failed. Parse the message for details (e.g., API returned HTTP 403: Permission denied).

Q4: High-risk operation fails with permission error?

Cause: High-risk operations require safety conditions.

Solution:

1. Set Confirm: true
2. Provide Reason parameter explaining the operation purpose
3. Verify account has permissions for high-risk operations
4. Confirm device is online (some commands require online device)