Skip to content

Error taxonomy

When a request fails, AzScraper returns a JSON error envelope. Use error.code for programmatic handling; error.message is diagnostic text and may change.

{
  "success": false,
  "error": {
    "code": "JOB_NOT_FOUND",
    "message": "Job not found",
    "details": []
  }
}
Field Meaning
success false for an error response.
error.code Stable, machine-readable code. Use it to handle errors in your integration.
error.message Diagnostic message. Do not use it as a stable programmatic value.
error.details Optional validation details.
error.correlationId May appear on an unhandled 500 response. Include it when you contact support.

Common request errors

HTTP Code Meaning / next step
400 VALIDATION_ERROR Request body, parameter, or cron expression is invalid. Check the field details.
400 INVALID_ASIN A product target is not a valid ASIN or supported product URL.
400 INVALID_WEBHOOK_URL A webhook URL is missing or is not a valid HTTP(S) URL.
401 UNAUTHORIZED The Bearer key is missing, invalid, or revoked.
402 INSUFFICIENT_CREDITS The account does not have enough credits to create or retry this job.
402 PLAN_UPGRADE_REQUIRED The requested schedule cadence or feature requires a different plan.
403 FORBIDDEN The key cannot access the requested project's resource. Check the project ID and key scope.
404 JOB_NOT_FOUND, SCHEDULE_NOT_FOUND, WEBHOOK_NOT_FOUND The requested resource was not found in the key's project.
429 RATE_LIMITED The request was throttled. Back off before retrying.
500 INTERNAL_ERROR Unexpected server error. Retry with backoff; include correlationId when contacting support.

Client handling

  1. Parse the JSON response and handle the error based on error.code.
  2. For 401, check the secret store and replace a revoked key.
  3. For 403, confirm that the project ID matches the key's project.
  4. For 402, stop automatic retries and check credits or plan access in the dashboard.
  5. For transient 429 or 5xx, retry with exponential backoff and jitter.