⚠️

Documentation Disclaimer

This documentation is not exhaustive and does not guarantee system behavior. Integrators are responsible for testing against actual API responses. See Documentation Disclaimer for full details.

Async Job Processing & Error Handling

All write operations in the Yelp Ads API (create, modify, terminate) are asynchronous. Understanding this model is critical to building a reliable integration.

Table of Contents

• How Async Jobs Work
• Polling for Status
• Terminal States
• Error Structure & PARENT_WAS_REJECTED
• Common Rejection Errors
• Concurrency & Race Conditions

How Async Jobs Work

Every create, modify, or terminate request returns a job_id immediately:

{ "job_id": "prvtN-nilb4mUynGGgKuBQ" }

This response only confirms the job was queued — not that it succeeded. Validation happens in a background worker, not at submission time. A 200 response with a job_id is a receipt, not a confirmation.

Jobs can be accepted and later REJECTED. Never infer success from the initial response alone.

Polling for Status

Poll GET /v1/reseller/status/{job_id} until the job reaches a terminal state:

curl \
  -X GET \
  --user "{username}:{password}" \
  https://partner-api.yelp.com/v1/reseller/status/<job_id>

Always store the job_id from each submission. You will need it to confirm outcomes and debug rejections.

Terminal States

Do not assume PROCESSING will always resolve to COMPLETED. Always poll until COMPLETED or REJECTED.

Error Structure & PARENT_WAS_REJECTED

Errors appear at two levels in the response:

1. business_results.status = REJECTED — the business-level request failed (e.g. business is closed or restricted)
2. update_results.program_added.status = REJECTED — the program-level operation failed even if the business-level status is COMPLETED

PARENT_WAS_REJECTED

When a top-level field fails validation, all child fields are automatically marked PARENT_WAS_REJECTED. This is cascading — it does not mean every field independently failed.

How to debug: Ignore all PARENT_WAS_REJECTED entries and find the single field with a specific error code. That is the root cause.

Example: an invalid ad_categories value will cause every other field (start, end, budget, etc.) to show PARENT_WAS_REJECTED, but the actual error is only on ad_categories.

Common Rejection Errors

Concurrency & Race Conditions

Do not submit overlapping updates to the same program simultaneously.

If two jobs targeting the same program_id are in flight at the same time, the last one to complete wins. The earlier job's changes may be silently overwritten.

Best practice: Wait for a terminal state (COMPLETED or REJECTED) before submitting another modification to the same program.