The API returns standard HTTP success or error status codes for all operations. For errors, the response will include the corresponding error code, a short message describing the cause of the error, and optionally additional fields conveying information specific to that error.
Status codes
| code | name | description |
|---|---|---|
| 200 | OK | The request was processed succesfully. |
| 201 | Created | The request was processed successfully, and a new resource instance was created. |
| 400 | Bad Request | The API was unable to process the request as it was malformed in some way. |
| 401 | Unauthorized | The API was unable to find valid credentials in the request. |
| 403 | Forbidden | The credentials provided do not have sufficient permissions to perform the request. |
| 404 | Not Found | The requested resources cannot be found. |
| 429 | Too Many Requests | The request has not been processed as a rate limit has been reached. |
| 5xx | Internal Server Error | An unexpected error occurred while processing the event. |
Error codes
invalid-body
The API was unable to process the body of your request. Make sure the request body is valid JSON.
invalid-parameter
One or more parameters in your request body did not pass validation checks. This response will include a params attribute with more detail on offending parameters.
unconfigured
Your organisation does not have the configuration required for the API to complete this request. The message will include details on which configuration is missing.
missing-scope
Your organisation, key or current user does not have the required permission scopes to perform this request.
limit-exceeded
The request could not be completed as it would breach a limit imposed on your organisation, key or current user. For example, a user who is limited to access two iCloud account per month will receive this error if attempting to access a third account.
session-expired
The session you are trying to use for this request has been marked as expired by the API. You must create a new, valid session before proceeding.
invalid-credentials
The provided credentials were rejected by the external service. Either the source does not exist (i.e. invalid username) or the credentials payload is wrong (such as a wrong password).
source-locked
The source has been locked by the external service and cannot be accessed by the API until unlocked by the user. The API message will provide instructions on how to do this for the relevant service.
code-required
The source you are trying to create a session against has multi-factor authentication (MFA) enable. The API will have triggered the MFA process, and you must provide the code presented during this process on your next session creation attempt.
For more details on the session creation flow, see the service reference for the service you are trying to access.
code-rate-limited
The user has attempted to create a session using an invalid code to often and has been rate-limited by the service. We recommend the user wait at least an hour before retrying.
choice-required
The source you are trying is to access has 2-step verification (2SV) enabled, a subset of multi-factor authentication (MFA). As part of this response, the API will provide a list of devices it can trigger the 2SV process against; this device will receive the 2SV code which will be needed for the next step in the process.
For more details on the session creation flow, see the service reference for the service you are trying to access.
task-error
A generic task error occurred. Retrying the poll or task might resolve the issue. Please contact support if the issue persists.
iCloud service error codes
icloud-terms-not-accepted
The user has not accepted the latest iCloud Terms of Service. They can accept the terms by signing into the App Store on an iOS or macOS device using their account, or by going to iCloud.com.
icloud-account-not-verified
The primary email address associated with the iCloud account has not yet been verified. The user must complete the email verification process to activate the account. The verification process can be managed by signing into appleid.apple.com.
icloud-web-access-required
Access to iCloud Data on the Web is turned off for the account. See Apple’s support article to enable it.
icloud-adp-enabled
Advanced Data Protection is enabled for the iCloud account, which is not supported by the API. See Apple’s support article to learn how to disable it.
icloud-signin-rate-limited
Access to the iCloud account is being rate limited by Apple, usually due to too many failed attempts at session initialisation. Please try again later.
icloud-account-locked
Access to the iCloud account has been blocked by Apple, typically for security reasons. Contact Apple support to learn more about unlocking the account.
icloud-service-not-activated
The iCloud service necessary to complete the operation has not been activated on the iCloud account in use. For example, if the user has not enabled iCloud Photo Library on the account this error will be raised when attempting to retrieve icpl.photos.
Make sure the user has toggled on a service's associated settings to ensure it is activated.
icloud-service-outage
The operation could not be completed due to an iCloud outage. These are very rare and typically transient -- retrying within a few minutes should succeed. However, if the issue persists look for more information on the iCloud status page and the API status page, and contact support.