Developer choices
reCAPTCHA recognition SDKs vs raw HTTP requests
reCAPTCHA recognition SDKs vs raw HTTP requests. Compare inputs, responsibilities, and limits before choosing your reCAPTCHA integration.
By the easycaptcha team · Published

Raw HTTP submits to POST /v1/task and retrieves GET /v1/task/TASK_ID with bearer authentication. SDKs expose the existing create/get methods. Both routes use the same recognition inputs and completed boolean results.
Keep lifecycle handling explicit
An SDK does not remove the need to check queued, running, completed, and failed states. Save the task ID, enforce a sensible local waiting deadline, and distinguish HTTP errors from embedded task failures. Avoid duplicate creation after uncertain transport outcomes.
Choose for your application environment
Use a supported SDK when it fits your language and dependency policy. Raw HTTP can suit a small integration or a language without a packaged client. Validate your exact request against the API reference and exercise a replacement round either way.
Compare what the client library actually supplies
| Concern | SDK | Raw HTTP |
|---|---|---|
| Request methods | Language-specific create/get methods | POST and GET requests you construct |
| Types | Provided where supported by the SDK | Your models or generated schema types |
| Image preparation | Still your application | Your application |
| Polling policy | Your integration controls observation | Your integration controls observation |
| Browser state and cell mapping | Still your application | Your application |
The SDK reduces transport boilerplate and gives a documented language interface. It does not know which browser image a task belongs to or whether the challenge changed after submission. Those responsibilities remain in application code regardless of whether the HTTP call is handwritten or wrapped by a client class.
Understand the native HTTP exchange
A native request goes to POST /v1/task with bearer authentication and the reCAPTCHA instruction, grid, and image data. The returned snapshot includes a task ID and status. Retrieve that same ID with GET /v1/task/TASK_ID while work remains queued or running, and inspect failed status before reading a result.
The reCAPTCHA documentation contains a complete curl example, including image placeholders that must be replaced with real encoded bytes. Raw HTTP is useful for understanding the contract and reproducing a request independently of an SDK. Keep paid keys out of shared command history and diagnostic output when using operational tooling.
Choose a backend that fits the runtime
The Python SDK offers the documented synchronous and asynchronous backends. The JavaScript/TypeScript SDK exposes asynchronous task methods with supported HTTP backends. Choose according to your application’s runtime, dependency policy, and existing error handling, rather than assuming a client library automatically retries or waits until every task is complete.
For a language without a suitable packaged client, raw HTTP or generated types from the OpenAPI schema may be appropriate. In either case, test serialized request fields and completed result shapes at the boundary. A typed program can still send the wrong image or apply the answer to the wrong local round.
Preserve the same failure semantics in both implementations
Treat an initial creation timeout as an uncertain submission, not proof that no work exists. Preserve a returned ID and retry observation of known work as appropriate. A local waiting deadline does not establish server-side cancellation, and an SDK exception does not replace checking embedded task failure in a successful response.
If you compare an SDK client with a raw HTTP client, use the same input snapshots, polling observation policy, and outcome definitions. Otherwise a latency difference may come from waiting behavior rather than transport overhead. The Python integration guide and JavaScript integration guide show the same lifecycle in concrete code.
Keep examples and production behavior aligned
A short code example often contains a simple polling loop to make the lifecycle visible. A production service may need persistent task records, a worker queue, bounded observation, and a later reconciliation pass. Those application choices apply to SDK and raw HTTP clients alike. Do not mistake omitted infrastructure in an example for an automatic guarantee supplied by the library.
Use one set of internal fixtures to validate both client paths if your application supports them. Compare the serialized recognition inputs, terminal result mapping, and behavior after an embedded failure. For timeout cases, confirm separately what happens when creation is uncertain and when retrieval of a known task fails.
When a transport backend changes, rerun those contract checks before broadening live trials. A backend can differ in exception types, timeout configuration, or request construction while leaving the recognition contract unchanged. Keep those details isolated from browser state management so a transport update does not unexpectedly alter cell ordering or trigger unconditional creation retries. This separation makes either implementation easier to maintain and review.
Frequently asked questions
Do SDKs change how reCAPTCHA selections are ordered?
No. Full grids remain row-major and dynamic results follow submitted image order.
Does an SDK remove the need for polling policy?
No. Your integration still needs to handle nonterminal states, observation deadlines, task errors, and ambiguous creation outcomes.
Does raw HTTP change selection ordering?
No. The native answer contract remains row-major for full grids and input-order for dynamic batches.