API versions Authentication Captcha and validation Creating an app Errors Making API requests Media attachments Methods Objects Smithereen vs VKontakte Text formatting Uploading files

Captcha

Some actions have "soft" rate limits that apply before the action is limited completely. In case such a soft rate limit is hit, the user can proceed with the action after solving a captcha.

In case when such an action is being performed using the API, the error 14: Captcha needed will be returned. The error object will contain the captcha object, with the following fields:

• url, the URL of the image to display
• width and height, the dimensions of the image
• sid, an opaque string that you need to pass back to the server
• hint, a localized description of what the user needs to do to be displayed in the UI, e.g. "enter the code from the image"

Your app should present this image, preferably accompanied by the hint, to the user, along with a text field to enter their response. After the user submits the response, repeat the request that returned the error with these extra parameters and without changing any other parameters:

• captcha_sid, the sid you received in the error
• captcha_answer, whatever the user has entered

To test how your app handles this error, use the utils.testCaptcha method.

If you can't or don't want to support handling this error in your app, treat it the same as error 9: Flood control.

Web-based validation

Some actions may require a more complex challenge than entering something from an image, or some other kind of confirmation like having the user re-enter their password. This is done via a web page.

Smithereen doesn't currently return this for any requests, but it might in a future version. This feature is thus optional but recommended to support for client apps, and entirely optional for other types of apps.

When validation is required, the error 17: Validation required will be returned, with the extra validation_url field containing the URL to be opened in a web view (for native apps) or an iframe (for web apps). Before you open the URL, add the redirect_url query parameter to it, which is the URL that will receive the callback after validation is finished or canceled. Information is passed back to your app by adding a fragment (after #) with query-string syntax to your redirect URL.

If the validation was successful, you will receive the following parameters:

• success = 1
• key, an opaque string you need to pass as validation_key when repeating the request that returned the error

If it was not, there will be one parameter, error = 1.

To test how your app handles this error, use the utils.testValidation method.

If you can't or don't want to support handling this error in your app, treat it the same as error 7: Permission to perform this action is denied.