Documentation

Copy page

Core Concepts

Understanding these key concepts will help you integrate effectively with the SalesCaddie API.

---

Idempotency

To prevent duplicate campaign creation, we recommend including an Idempotency-Key header with each request. While not required, it provides the best protection against duplicate processing.

What is Idempotency?

Idempotency means you can safely retry the same request multiple times without creating duplicate resources. If you send the same request twice with the same idempotency key, we'll process it only once.

Usage

Include the Idempotency-Key header with a unique identifier for the event:

Code
 
Idempotency-Key: UNIQUE-EVENT-12345

Complete Example

Code
 
curl -X POST https://api.salescaddie.dev/v1/deals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: UNIQUE-EVENT-12345" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

What Makes a Good Idempotency Key?

Good Examples:

• ✅ EVENT-12345 (your system's unique event ID)
• ✅ tenant-abc-event-67890 (tenant + event ID)
• ✅ uuid-a7b2c3d4-e5f6-7890 (generated UUID)

Bad Examples:

• ❌ request-1 (not unique across time)
• ❌ timestamp-1699564800 (timestamp alone)
• ❌ Random values that change on each retry

---

Rate Limits

To ensure fair usage and system stability, we enforce rate limits on API requests.

Current Limits

Limit	Value
Requests per minute	100
Requests per hour	1,000
Requests per day	10,000

Rate Limit Headers

Every API response includes rate limit information:

Code
 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699564800

• X-RateLimit-Limit: Your total allowed requests per window
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Unix timestamp when the window resets

Exceeding Limits

If you exceed your rate limit, you'll receive a 429 Too Many Requests response:

Code
 
{
  "type": "https://httpstatuses.com/429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please retry after 60 seconds.",
  "instance": "/v1/deals",
  "trace": {
    "timestamp": "2025-11-13T22:41:48.080Z",
    "requestId": "abc123-request-id",
    "buildId": "5333d1e2-475a-4ae6-a66a-0105505b3a6f",
    "rayId": "99e1c752dfef2ed3"
  }
}

---

Error Handling

All API errors follow the RFC 7807 standard format for consistent, machine-readable error responses, with additional trace information for debugging.

Error Response Format

Code
 
{
  "type": "https://httpstatuses.com/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid phone number format for customer.phone",
  "instance": "/v1/deals",
  "trace": {
    "timestamp": "2025-11-13T22:41:48.080Z",
    "requestId": "7bb3a7ac-29a5-4d40-8ed5-54f49a8c7858",
    "buildId": "5333d1e2-475a-4ae6-a66a-0105505b3a6f",
    "rayId": "99e1c752dfef2ed3"
  }
}

RFC 7807 Standard Fields:

• type: URI reference identifying the error type
• title: Human-readable error summary
• status: HTTP status code
• detail: Specific details about this error occurrence (may not be present for some errors)
• instance: The API endpoint that generated the error

Additional Trace Information:

• trace: Debugging information included in all responses
  • timestamp: When the error occurred
  • requestId: Unique request identifier - always include this when contacting support!
  • buildId: API deployment version
  • rayId: Infrastructure trace ID

Common Status Codes

Code	Meaning	When It Happens
202	Accepted	Request successfully queued
400	Bad Request	Invalid data format or validation failure
401	Unauthorized	Missing or invalid API key
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error (we're notified automatically)

---

Next Steps

→ Review Authentication best practices

→ Explore the API Reference for detailed endpoint documentation

→ Need help? Check out Support