Retreaver Ping Shield

Retreaver Ping Shield protects your Retreaver account and buyers from excessive or wasteful pings in the industry, without disrupting valid requests. By filtering out unnecessary traffic, Ping Shield helps increase the number of qualified calls delivered — and ultimately, your revenue.

Ping Shield operates on both sides of Retreaver’s request flow:

• Inbound requests – traffic coming from affiliates into Retreaver.

• Outbound requests – traffic Retreaver sends to buyers through campaigns.

Unlike a simple rate limiter, Ping Shield is an intelligent subsystem of Retreaver. It applies a set of adaptive rules to prevent unnecessary inbound and outbound requests that could negatively affect account operations.

This protection isn’t just technical — it safeguards relationships. For example, if a buyer receives too many requests on your behalf without enough valid calls, they may stop working with you. Ping Shield helps you prevent this by ensuring your traffic remains clean, balanced, and trustworthy.

Below is a list of features applied to both inbound and outbound requests.

Inbound Duplicate Caller Number

This Ping Shield feature protects buyers within a campaign by preventing unnecessary webhook requests. If there is already an active (non-expired) reservation for a caller’s number, additional requests are blocked from being sent to the buyer.

By eliminating duplicate requests, the number of requests sent to buyers is dramatically reduced. Without this protection, some platforms repeatedly send the same caller number — sometimes just milliseconds apart — overwhelming buyers with redundant requests. Ping Shield ensures buyers only receive meaningful, properly spaced requests, keeping their systems efficient and their trust intact.

A caller number can be considered a duplicate either at the postback key level or at the campaign level. There isn’t a universally correct answer to which approach you should use.

For example, should two different publishers be allowed to send requests for the same caller number? The right choice depends on your business model and use case. Retreaver gives you the flexibility to decide — and provides two tools to help you manage this behavior.

Duplicate Caller Number based on Postback Key 

If the same caller number is sent by the same postback key while a reservation is still active (i.e. not expired), Retreaver will return the existing reservation to the client. In this case, no additional webhook requests will be sent to buyers in the campaign.

The example below demonstrates how the first request for +15855752500 creates and returns a reservation. Any subsequent requests from the same postback key will return the same reservation until it expires.

Example with one affiliate:
Sending the first request:

# Request
% curl -X POST "https://rtb.retreaver.com/rtbs.json?key=28a1cb04-da3f-4827-a46c-ec6e414513cf" \
	-H "Content-Type: application/json" \
	-d '{
	      "publisher_id": "cee04aa8", 
	      "caller_number": "+15855752500"
	    }'
# Response
{
  "uuid": "1e944d88-0dd7-4ad6-a495-97de9e629d4f",
  "status": "reserved",
  "retreaver_payout": 34.0,
  "retreaver_seconds": 90,
  "inbound_number": "+18887503175",
  "expires_at": "2025-10-01T12:02:59.475Z"
}
  

Sending the second request:

# Request
% curl -X POST "https://rtb.retreaver.com/rtbs.json?key=28a1cb04-da3f-4827-a46c-ec6e414513cf" \
	-H "Content-Type: application/json" \
	-d '{
	      "publisher_id": "cee04aa8", 
	      "caller_number": "+15855752500"
	    }'
# Response
{
  "uuid": "1e944d88-0dd7-4ad6-a495-97de9e629d4f",
  "status": "reserved",
  "retreaver_payout": 34.0,
  "retreaver_seconds": 90,
  "inbound_number": "+18887503175",
  "expires_at": "2025-10-01T12:02:59.475Z",
  "retreaver_ping_shield": true
}

Notice that the second request includes the property retreaver_ping_shield. This flag indicates that the request was shielded and that the existing reservation was returned instead of generating a new one.

The uuid in both cases is the same. 

Example with two affiliates with two different postback keys:

Both of them will receive their own reservation

Sending first request

# Request
% curl -X POST "https://rtb.retreaver.com/rtbs.json?key=28a1cb04-da3f-4827-a46c-ec6e414513cf" \
	-H "Content-Type: application/json" \
	-d '{
	      "publisher_id": "cee04aa8", 
	      "caller_number": "+15855752500"
	    }'
# Response
{
  "uuid": "726c2e32-4513-476a-8580-24e0401afb83",
  "status": "reserved",
  "retreaver_payout": 34.0,
  "retreaver_seconds": 90,
  "inbound_number": "+18446723038",
  "expires_at": "2025-10-01T12:04:48.661Z"
}

Sending the second request

# Request
% curl -X POST "https://rtb.retreaver.com/rtbs.json?key=7070c73f-2db8-434b-a2a3-ee63cbaadde2" \
	-H "Content-Type: application/json" \
	-d '{
	      "publisher_id": "cee04aa8", 
	      "caller_number": "+15855752500"
	    }'
# Response
{
  "uuid": "398a4f16-3840-4e98-89d9-713f1491554b",
  "status": "reserved",
  "retreaver_payout": 34.0,
  "retreaver_seconds": 90,
  "inbound_number": "+18776808890",
  "expires_at": "2025-10-01T12:05:42.774Z"
}

Both affiliates receive valid reservations for the same caller number.

• Affiliate 1: reservation 726c2e32-4513-476a-8580-24e0401afb83 for caller +15855752500

• Affiliate 2: reservation 398a4f16-3840-4e98-89d9-713f1491554b for caller +15855752500

Since the requests are coming through different postback keys, both affiliates are allowed to send requests for the same caller number without conflict.

Duplicate Caller Number based on Affiliate 

If the same caller number is sent by the same affiliate/publisher/source while a reservation is still active (i.e. not expired), Retreaver will return the existing reservation to the client even. In this case, no additional webhook requests will be sent to buyers in the campaign.

The example below demonstrates how the first request for +15855752500 creates and returns a reservation. Any subsequent requests from the same postback key will return the same reservation until it expires.

Example with one affiliate:
Sending the first request:

# Request
% curl -s -X POST "https://rtb.retreave.com/rtbs.json?key=98718047-2cc6-497b-a5fb-93674bc3a060" \
    -H "Content-Type: application/json" \
	-d '{
	      "source_id": "266747", 
	      "caller_number": "+15855752500"
	    }'

# Response
{
  "uuid": "e456a3bb-f43f-4bff-85dd-46fbed5899f9",
  "status": "reserved",
  "retreaver_payout": 0.0,
  "retreaver_seconds": 90,
  "inbound_number": "+18556272197",
  "expires_at": "2025-10-31T08:54:15.501Z"
}
  

Sending the second request from a different postback key but same affiliate:

# Request
  % curl -s -X POST "https://rtb.retreave.com/rtbs.json?key=04c2a7c8-13c1-4b82-958f-82b61d2099b5" \
    -H "Content-Type: application/json" \
	-d '{
	      "source_id": "266747", 
	      "caller_number": "+15855752500"
	    }'

# Response
{
  "uuid": "e456a3bb-f43f-4bff-85dd-46fbed5899f9",
  "status": "reserved",
  "retreaver_payout": 0.0,
  "retreaver_seconds": 90,
  "inbound_number": "+18556272197",
  "expires_at": "2025-10-31T08:54:15.501Z",
  "retreaver_ping_shield": true
}

Notice that the second request includes the property retreaver_ping_shield. This flag indicates that the request was shielded and that the existing reservation was returned instead of generating a new one.

The uuid in both cases is the same even though the request was made from different postback keys. 

Example with two affiliates from the same postback key:

Both of them will receive their own reservation

Sending first request

# Request
% curl -X POST "https://rtb.retreaver.com/rtbs.json?key=98718047-2cc6-497b-a5fb-93674bc3a060" \
	-H "Content-Type: application/json" \
	-d '{
	      "publisher_id": "cee04aa8", 
	      "caller_number": "+15855752500"
	    }'
# Response
{
  "uuid": "c705759d-ffc8-490d-87e0-d9ebaeafd058",
  "status": "reserved",
  "retreaver_payout": 34.0,
  "retreaver_seconds": 90,
  "inbound_number": "+18446723038",
  "expires_at": "2025-10-01T12:04:48.661Z"
}

Sending the second request

# Request
% curl -X POST "https://rtb.retreaver.com/rtbs.json?key=98718047-2cc6-497b-a5fb-93674bc3a060" \
	-H "Content-Type: application/json" \
	-d '{
	      "publisher_id": "266747", 
	      "caller_number": "+15855752500"
	    }'
# Response
{
  "uuid": "c2610ac5-9c08-4ad1-8556-7d00af7af780",
  "status": "reserved",
  "retreaver_payout": 34.0,
  "retreaver_seconds": 90,
  "inbound_number": "+18776808890",
  "expires_at": "2025-10-01T12:05:42.774Z"
}

Both affiliates receive valid reservations for the same caller number.

• Affiliate 1: reservation c705759d-ffc8-490d-87e0-d9ebaeafd058 for caller +15855752500

• Affiliate 2: reservation c2610ac5-9c08-4ad1-8556-7d00af7af780 for caller +15855752500

Since the requests are coming through different affiliates/publishers/sources, both affiliates are allowed to send requests for the same caller number without conflict.

Duplicate Caller Number based on Campaign

If the same caller number is sent within the same campaign while a reservation is still active (i.e. not expired), Retreaver will create a valid reservation for the first request. Any subsequent requests (second, third, etc.) for that caller number will return a response with the status ping_shield_already_reserved.

In this scenario, no additional webhook requests are sent to buyers in the campaign for duplicate caller numbers submitted by any affiliate.

The example below shows how the first request for +15855752500 creates and returns a reservation, while subsequent requests return a response containing ping_shield_already_reserved.

To enable this feature, navigate to Campaign → Toggles and activate Ping Shield by Campaign and Caller Number.

Example with two affiliates with two different postback keys in the same campaign when "Ping Shield by Campaign and Caller Number" is turned on:

Sending first request

# Request
% curl -X POST "https://rtb.retreaver.com/rtbs.json?key=28a1cb04-da3f-4827-a46c-ec6e414513cf" \
	-H "Content-Type: application/json" \
	-d '{
	      "publisher_id": "cee04aa8", 
	      "caller_number": "+15855752500"
	    }'
# Response
{
  "uuid": "41a85397-5092-42e1-9e3c-15f077443f15",
  "status": "reserved",
  "retreaver_payout": 34.0,
  "retreaver_seconds": 90,
  "inbound_number": "+18883359576",
  "expires_at": "2025-10-01T12:08:17.334Z"
}

Sending the second request

# Request
% curl -X POST "https://rtb.retreaver.com/rtbs.json?key=7070c73f-2db8-434b-a2a3-ee63cbaadde2" \
	-H "Content-Type: application/json" \
	-d '{
	      "publisher_id": "12e55bs7", 
	      "caller_number": "+15855752500"
	    }'
# Response
{
  "uuid": "8f3bfaf5-37ac-4b49-8582-b634de08e324",
  "status": "ping_shield_already_reserved",
  "retreaver_ping_shield": true
}

On the first request, Affiliate 1 receives a valid reservation:

• Affiliate 1 → reservation 41a85397-5092-42e1-9e3c-15f077443f15 for caller +15855752500

When Affiliate 2 submits a request for the same caller number, Retreaver responds with:

• Affiliate 2 → reservation 8f3bfaf5-37ac-4b49-8582-b634de08e324 for caller +15855752500 with status ping_shield_already_reserved. The call is not sent.

Even though the requests are made through different postback keys, the campaign has the Ping Shield by Campaign and Caller number feature enabled, so only the first affiliate is granted a valid reservation.

Outbound Safety caps

Retreaver sends webhooks on key events, such as when a call starts or when an availability check is needed for an endpoint buyer. While Retreaver is designed to handle — and can generate — virtually unlimited outbound requests per second, most external systems cannot, should not, or simply will not process traffic at that scale.

That’s where Retreaver Ping Shield Safety Caps come in. They act as a protective guardrail: if too many requests are sent to external systems, those systems may begin rate-limiting the traffic. At that point, sending additional requests provides no benefit and could even be harmful. Safety Caps ensure that your integrations stay efficient, reliable, and respectful of partner system limits.

Examples of rate limit responses from external systems

If you see responses like this, it means that the systems we are pinging on your behalf are rate limiting the requests. 

  {
  "success": "false",
  "error": "Daily cap limit reached - Please contact your account rep"
  }
  

  {
  "statusCode": 429,
  "message": "Too many ping requests. Please slow down and try again later.",
  "error": "Too Many Requests",
  "timestamp": "2025-09-17T20:52:01.787Z",
  "path": "/v1/rtb/ping",
  "requestId": "d2ab04b1-5fb0-4160-9965-f6b263ab1af6",
  "code": "HTTP_429"
}

  {
  "response": {
    "status": "error",
    "message": "You have exceeded your ping limit. Please contact us to increase your limit."
  }
}

  {
  "error": {
    "code": 1024,
    "message": "rate-limited"
  }
}

  {
  "error": "FAILED Request is already being processed",
  "retreaver_ping_shield": true
}

Drawbacks and risks

Continuing to send requests to systems that are already rate limiting you carries significant risks. The most obvious is that your requests may be blocked entirely for an extended period of time. If that happens, you lose the ability to send traffic to those call endpoints or buyers.

What are Retreaver Ping Shield Safety Cap?

In these scenarios, Retreaver Ping Shield Safety Caps automatically activate to protect you and your partners.

• They prevent your requests from being permanently blocked by external systems.

• They also protect the health and stability of those external systems by reducing unnecessary load.

When Ping Shield detects excessive rate limiting, it temporarily lowers the number of outbound pings.

How Ping Shield Refreshes?

External systems often enforce rate limits such as per second, per 10 seconds, or per minute. To align with this, Ping Shield monitors requests in 10-second intervals.

If you hit the Safety Cap, some webhooks may not fire immediately. However, the cap is automatically re-evaluated within 1 to 10 seconds, and normal traffic resumes as soon as conditions allow.

Can the Safety cap be increased?

Technically, Retreaver can send billions of requests per second — but doing so after an external system has already started rate limiting is meaningless and counterproductive.

The Safety Cap is designed to engage only after you’ve exceeded the external system’s capacity multiple times, ensuring the rate limiting is clearly visible in your Fired Pixels logs. Raising the cap won’t improve results, because requests sent beyond the external system’s threshold are simply discarded or blocked.

What should you do and why are there so few calls?

We’ve seen cases where companies send millions of requests per day to external systems, yet only generate a few hundred calls. In these cases, 70–80% of requests are rate limited and provide no benefit.

Sending more requests does not mean more calls. In fact:

• Doubling requests often reduces successful calls.

• Sending 10x more requests can result in zero calls for the day, because buyers block your traffic completely.

Sending more requests usually means receiving fewer calls.

Best practices:

• Reduce the volume of requests sent to buyers.

• Use the RTB Log to identify where excess pings are coming from.

• Evaluate their quality by reviewing claim-to-call ratios.

• Pause publishers or keys that generate pings but do not deliver calls.