Orkut Application Platform

The orkut Client Library - Errors and Captchas

Bruno Oliveira - Developer Relations
December 2010

This section of the guide explains how to perform common operations involving erros and captchas using the orkut Client Library. If you haven't read it yet, please read the Introduction to the Client Library first, since we'll assume you know how to perform the library and environment setup.

Contents:

Errors

Errors can happen, and handling them correctly is an essential part of development. There are two ways in which errors are signaled by the library:


  • Transaction failures: when a transaction fails on the server side, it returns with an error flag that you can query with its hasError() function. Then you can obtain more information about the error by calling getError() function. This type of error is not signaled as an exception, so you must query for it yourself after submitting each batch.

  • Exceptions: most of the OrkutAdapter functions may throw an OrkutAdapterException. The exception is thrown when a library-level error is encountered. You should always handle this exception to inform the user that something went wrong.

Handling the OrkutAdapterException is a very standard process: you have to handle it like any other exception. Therefore, we will not focus on that on this section.

The transaction failures, however, are not exceptions: you must check for them yourself:

BatchTransaction btx = orkad.newBatch();
btx.add(tx);  // tx is a transaction you created earlier
orkad.submitBatch(btx);

if (tx.hasError()) {
   OrkutError error = tx.getError();
   // handle error
   // TODO
}

There are several possible types of errors, and you can query for each type with the is*() functions of the OrkutError object:

  • isAuthenticationFailure()
  • isCaptchaError()
  • isTosNotAcceptedByUser()
  • isApiLimitExceeded()
  • isInvalidUser()
  • isNoPermission()
  • isAlbumDoesNotExist()
  • isInvalidPhoneNumber()

You can also use these two functions that report on the general nature of the error:

  • isClientError()
  • isServerError()

You can also query for the error type with errorType() and obtain the message with getMessage().

If you simply want to print the error for debugging purposes, you can just convert the OrkutError object to a string (using the built-in toString() method), which will result in a string that indicates the error code, type and message:

if (tx.hasError()) {
   OrkutError error = tx.getError();
   say("*** Error: " + error.toString());
}

Captchas

Your code should always be prepared to present captchas to the user on any transaction request. Captchas are necessary in order to ensure that the API is not abused. When the platform requires you to submit the solution to a captcha, it will signal that condition by means of an OrkutError whose type is ErrorType.REQUIRES_CAPTCHA (you can easily whery for that using isCaptchaError()).

If this error is returned in a transaction, you must ask the user to solve a captcha and resubmit the transaction batch, this time with the solution to the proposed captcha.

The captcha image can be obtained by two methods:

  • You can call the getCaptchaImage() on your OrkutAdapter, which will return the image as a byte array.

  • You can call saveCaptchaToFile() on the OrkutAdapter in order to save the image to a file.

In either case, you should show the image to the user and ask him to type the characters that appear in the image. After that, you must call submitBatchWithCaptcha() to resubmit your transaction batch.

Here is a code snippet that illustrates the process:

BatchTransaction btx = orkad.newBatch();
btx.add(tx);
say("Sending transaction...");
orkad.submitBatch(btx);

if (tx.hasError()) {
   OrkutError error = tx.getError();
   if (error == null || !error.isCaptchaError()) {
      say("*** Error submitting transaction.");
      if (error != null) say(error.toString());
      return;
   }
   say("Captcha solving is required. Downloading.");
   orkad.saveCaptchaToFile(error, "captcha.jpg");

   say("Now open the file captcha.jpg with your favorite image viewer.");
   say("What is the text in the image?");
   String answer = readline();

   say("Submitting transaction with captcha...");
   orkad.submitBatchWithCaptcha(btx, error, answer);
}

Naturally, the rudimentary approach that this snippet takes is okay for debugging purposes but wouldn't befit a production application. If you are writing a web application, you would want to display the image in web page; if you are writing a desktop application, you would want to load the image into your UI to show it to the user.

Known issue: as of the time of the writing of this document, there appears to be an issue where the server does not reliably report whether a submitted captcha solution was successful or not. We'll try to debug it or find a workaround and will update this document once we do.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.