How to submit reports

Reports matter. Not the kind you file after an incident, but the lightweight, programmatic signals—reportCorrect and reportIncorrect—that feed intelligence back into the 2Captcha system. Optional? Technically, yes. Critical? Absolutely. When implemented with intention, this feedback loop sharpens recognition accuracy, trims unnecessary spend, and accelerates the identification of workers whose performance drifts below acceptable thresholds.

API v2 methods for report submission

reportCorrect — confirming a correct solution

Trigger this endpoint when the target website accepts the captcha solution without resistance. Think of it as a positive reinforcement signal, quietly training the system toward better outcomes.

Request Parameters:

Example Request (POST, JSON):

{
  "clientKey": "YOUR_API_KEY",
  "taskId": 74455221488
}

Example Successful Response:

{
   "errorId": 0,
   "status": "success"
}

Endpoint: https://api.2captcha.com/reportCorrect

reportIncorrect — reporting an incorrect solution

Use this when the solution fails validation on the target site. It is not a complaint button. It is a diagnostic instrument.

Refund Policy Notice:

• Each report undergoes individual review
• Standard captchas: answer accuracy is cross-validated
• Token-based captchas (reCAPTCHA, FunCaptcha): worker-level statistics drive decisions
• Refunds are never automatic; they are earned through signal quality

Request Parameters (identical to reportCorrect):

{
  "clientKey": "YOUR_API_KEY",
  "taskId": 74455221488
}

Endpoint: https://api.2captcha.com/reportIncorrect

Critical errors when submitting reports

ERROR_REPORT_NOT_RECORDED

What triggers it:

1. Your complaint ratio exceeds 40% on captchas that were, in fact, solved correctly, OR
2. You submit the report more than 15 minutes after the solution was delivered

Time is a constraint. Accuracy is non-negotiable.

Solution:

# Example reporting logic
def send_report(task_id, is_correct, solved_timestamp):
   from datetime import datetime, timedelta
  
   # Check time window constraint
   if datetime.now() - solved_timestamp > timedelta(minutes=15):
       logger.warning(f"Report skipped: timeout for task {task_id}")
       return False
  
   # Send reportIncorrect ONLY for genuinely incorrect solutions
   endpoint = "reportCorrect" if is_correct else "reportIncorrect"
   # ... send request

Best Practices:

• Reserve reportIncorrect for confirmed failures—never as a hedge
• Log solution timestamps religiously; they are your audit trail
• Never weaponize reporting endpoints for load testing or experimentation

ERROR_DUPLICATE_REPORT

The system remembers. Submitting the same taskId twice yields this error—not as punishment, but as protection against noise.

Solution:

# Track submitted reports in cache/database
reported_tasks = set()

def safe_report(task_id, is_correct):
   if task_id in reported_tasks:
       logger.info(f"Duplicate report skipped for task {task_id}")
       return {"errorId": 0, "status": "already_reported"}
  
   # Submit report...
   reported_tasks.add(task_id)
   return response

Best Practices:

• Maintain a client-side ledger of reported taskIds
• Design for idempotency: one task, one report, one truth
• Check state before sending; avoid optimistic retries on duplicates

How the report processing system works

For standard captchas (image-based, text):

1. You flag a solution with reportIncorrect
2. The system assigns re-verification to a worker with proven reliability
3. A comparison unfolds:
   • Answers align → Your complaint is dismissed; both workers are compensated
   • Answers diverge → You receive a balance refund; the original worker is penalized

It is arbitration, automated.

For token-based captchas (reCAPTCHA v2/v3, FunCaptcha, KeyCaptcha):

Re-verification isn't always possible. So the system adapts.

• Worker-level statistics accumulate over time
• High reportIncorrect rates trigger gradual restrictions on captcha type access
• For reCAPTCHA v3, reputation adjustments are scoped to the domain in question

No single report decides fate. Patterns do.

Why submitting both report types matters

Critical reminder: Never submit reportIncorrect speculatively. Cross the 40% false-complaint threshold, and the reporting feature may be suspended for your account. Precision builds trust. Noise erodes it.

Practical implementation guidelines

1. Timeouts and retry logic

// JavaScript example
async function sendReportWithRetry(taskId, isCorrect, maxRetries = 3) {
   for (let attempt = 1; attempt <= maxRetries; attempt++) {
       try {
           const response = await fetch(`https://api.2captcha.com/${isCorrect ? 'reportCorrect' : 'reportIncorrect'}`, {
               method: 'POST',
               headers: {'Content-Type': 'application/json'},
               body: JSON.stringify({
                   clientKey: 'YOUR_API_KEY',
                   taskId: taskId
               })
           });
           const result = await response.json();
          
           if (result.errorId === 0) return true;
          
           // Handle specific error codes
           if (result.errorCode === 'ERROR_REPORT_NOT_RECORDED') {
               console.warn('Report rejected: check timing or complaint ratio');
               return false;
           }
           if (result.errorCode === 'ERROR_DUPLICATE_REPORT') {
               console.info('Report already submitted');
               return true;
           }
          
           // Retry on network errors
           if (attempt < maxRetries) {
               await new Promise(r => setTimeout(r, 1000 * attempt));
               continue;
           }
       } catch (e) {
           console.error(`Attempt ${attempt} failed:`, e);
       }
   }
   return false;
}

2. Logging for debugging

import logging, json
from datetime import datetime

logger = logging.getLogger('captcha_reports')

def log_report(task_id, action, response, elapsed_ms):
   logger.info(json.dumps({
       'timestamp': datetime.utcnow().isoformat(),
       'task_id': task_id,
       'action': action,  # 'correct' or 'incorrect'
       'error_id': response.get('errorId'),
       'error_code': response.get('errorCode'),
       'response_time_ms': elapsed_ms
   }))

Logs aren't just for post-mortems. They're your real-time compass.

3. Quality monitoring

• Monitor the ratio: reportIncorrect divided by total solved captchas
• Expect 1–15% under normal conditions, varying by captcha complexity
• A sudden jump beyond 30% warrants investigation:
  • Integration logic may have drifted
  • The target site could have changed its validation rules
  • Your interpretation of "success" might need refinement

Helpful resources

• API v2 Documentation: https://2captcha.com/api-docs
• API Error Codes Reference: https://2captcha.com/api-docs/error-codes
• 2Captcha Support: https://2captcha.com/support/tickets
• Demo Page for Testing: https://2captcha.com/demo

Forward this to your engineering team if you're not the one writing the code. Done right, reporting logic can trim 20–30% off your long-term captcha resolution spend. That isn't optimization. That is leverage.

This article reflects the official 2Captcha documentation for API v2. Specifications evolve. Verify against source.

Conclusion

reportCorrect and reportIncorrect are not afterthoughts. They are feedback channels woven into the core of 2Captcha's operational intelligence. Used well, they create compounding returns: fewer errors, lower costs, smarter task routing, and a more resilient worker ecosystem.

But the system only learns what you teach it.

Submit reportIncorrect only when you are certain. Respect the 15-minute window. Track your submissions. Let data—not assumption—guide your signals.

Because in the end, the quality of your integration doesn't just affect your metrics. It shapes the behavior of the entire network.