AsyncGuard — API Reference

Authentication

All API requests require a Bearer token in the Authorization header. API keys can be found in your Dashboard → Settings page.

API Key Prefixes

ag_test_ — Test environment keys. No real data is sent to external platforms.
ag_live_ — Live environment keys. Operations are executed against production APIs.

Example Request Header

Authorization: Bearer ag_live_xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Keep your API keys secret. Never expose them in client-side code or public repositories. Rotate keys immediately if compromised.

Create Batch

Proxy a batch of records to Salesforce with automatic write serialization, grouping by parent record, and retry handling.

POST /api/v1/proxy/salesforce

Request Body

Parameter	Type	Description
operation required	string	One of `"insert"`, `"update"`, `"upsert"`, or `"delete"`
sobject required	string	Salesforce object type, e.g. `"Opportunity"`, `"Account"`
records required	array	Array of record objects. Minimum 1, maximum 10,000 items.
options.parentField optional	string	Override the parent field used for grouping records to prevent lock contention.
options.maxRetries optional	number	Maximum retry attempts (1–10). Default: `5`
options.priority optional	number	Processing priority (0–10). Higher values are processed first. Default: `0`

Example Request

curl

curl -X POST https://api.asyncguard.com/api/v1/proxy/salesforce \
  -H "Authorization: Bearer ag_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "update",
    "sobject": "Opportunity",
    "records": [
      { "Id": "006xx000001a", "StageName": "Closed Won", "Amount": 50000 },
      { "Id": "006xx000001b", "StageName": "Closed Won", "Amount": 75000 },
      { "Id": "006xx000001c", "StageName": "Negotiation", "Amount": 30000 }
    ],
    "options": {
      "parentField": "AccountId",
      "maxRetries": 3,
      "priority": 5
    }
  }'

Response

              Response
              202 Accepted
            

{
  "id": "batch_8f3a2b1c9d4e",
  "status": "queued",
  "groups": [
    { "parentKey": "001xx000003DGbX", "recordCount": 2 },
    { "parentKey": "001xx000003DGbY", "recordCount": 1 }
  ],
  "totalRecords": 3,
  "totalGroups": 2,
  "statusUrl": "/api/v1/proxy/salesforce/batch_8f3a2b1c9d4e/status"
}

Error Responses

              Authentication Error
              401
            

{ "error": "invalid_api_key", "message": "The provided API key is invalid or has been revoked." }

              Validation Error
              400
            

{ "error": "validation_error", "message": "records must contain between 1 and 10,000 items." }

              Rate Limit Exceeded
              429
            

{ "error": "rate_limit_exceeded", "message": "Monthly record limit reached. Upgrade your plan or wait until the next billing cycle." }

Check Batch Status

Retrieve the current status and progress of a previously submitted batch operation.

GET /api/v1/proxy/salesforce/{batchId}/status

Path Parameters

Parameter	Type	Description
batchId required	string	The batch ID returned from the Create Batch endpoint.

Example Request

curl

curl https://api.asyncguard.com/api/v1/proxy/salesforce/batch_8f3a2b1c9d4e/status \
  -H "Authorization: Bearer ag_live_xxxxx"

Response

              Response
              200 OK
            

{
  "id": "batch_8f3a2b1c9d4e",
  "status": "processing",
  "progress": {
    "total": 3,
    "completed": 1,
    "failed": 0,
    "pending": 1,
    "processing": 1
  },
  "totalRecords": 3,
  "groups": [
    {
      "parentKey": "001xx000003DGbX",
      "status": "completed",
      "recordCount": 2
    },
    {
      "parentKey": "001xx000003DGbY",
      "status": "processing",
      "recordCount": 1
    }
  ]
}

Status Values

Status	Description
queued	Batch has been accepted and is waiting to be processed.
processing	Records are actively being sent to Salesforce.
completed	All records processed successfully.
partial_failure	Some records failed after exhausting retries. Check group-level errors.

Retry Logic

AsyncGuard automatically retries operations that fail due to transient errors. Records are grouped by parent to prevent lock contention, and each group is retried independently.

Retryable Errors

The following Salesforce error codes trigger automatic retry:

Backoff Strategy

Retries use exponential backoff with jitter to avoid thundering herd problems:

Backoff Formula

// Base delay: 2 seconds
// Multiplier: 2^attempt
// Max delay: 5 minutes (300s)
// Jitter: +/- 30%

delay = min(2s × 2^attempt, 300s)
delay = delay × (1 + random(-0.3, 0.3))

Attempt	Base Delay	With Jitter Range
1	4s	2.8s – 5.2s
2	8s	5.6s – 10.4s
3	16s	11.2s – 20.8s
4	32s	22.4s – 41.6s
5	64s	44.8s – 83.2s

After all retry attempts are exhausted, the failed record group is moved to the dead letter queue. You can inspect and replay these from the Dashboard or via the API.

Rate Limits

Rate limits are based on your plan tier and measured by the number of records processed per month. When you exceed your limit, subsequent requests return 429 Too Many Requests.

Plan	Monthly Records	Limit
Free	For evaluation and testing	10,000 / mo
Starter	Small teams and projects	100,000 / mo
Professional	Growing organizations	1,000,000 / mo
Enterprise	Custom volume	Custom

Current usage is available in your Dashboard. The API also returns X-RateLimit-Remaining and X-RateLimit-Reset headers with every response.

Error Codes

All errors follow a consistent format with an error code and human-readable message.

HTTP Status	Error Code	Description
400	validation_error	Request body failed validation. Check required fields and value ranges.
401	invalid_api_key	API key is missing, invalid, or revoked.
403	forbidden	API key does not have permission for this operation.
404	not_found	The requested batch ID does not exist.
429	rate_limit_exceeded	Monthly record limit reached for your plan tier.
500	internal_error	An unexpected error occurred. Contact support if persistent.