Errors, limits & paging
Every endpoint follows the same rules for errors, rate limits, lists and data formats. Build them in once.
Errors
A failed request answers with an HTTP status and a JSON body in one shape. Branch on code, which is stable; show message to people, since it is written for them and may change.
{
"error": {
"code": "already_lead",
"message": "This person is already a lead for this offering.",
"details": null
}
}| Status | code | What happened | What to do |
|---|---|---|---|
| 400 | bad_request | The request can't be done as sent. | Read the message; fix the request. |
| 401 | invalid_api_key | The key is unknown, revoked or expired, or its creator left the business. | Check the key; create a new one if needed. |
| 401 | api_key_not_allowed | This endpoint needs a person signed in. | Do it in the app instead. |
| 403 | permission_denied | The key's role can't do this. | Use a key with a higher role. |
| 404 | not_found | No such record in this business (or the URL is wrong). | Check the id and the path. |
| 409 | conflict | It clashes with what already exists, e.g. already_lead, contact_archived. | Don't retry as is; use the existing record. |
| 409 | call_waiting | The call was asked for but can't start yet (employee paused, process off, no credits). | Nothing: the request is kept and the call starts by itself. |
| 422 | validation_error | A field is missing, has the wrong type, or isn't allowed. | Fix the fields listed in details. |
| 429 | rate_limited | Too many requests this minute. | Wait Retry-After seconds, then retry. |
| 500 | internal_error | Something failed on our side. | Retry with backoff; contact us if it lasts. |
| 503 | service_unavailable | A service we depend on is briefly down. | Retry with backoff. |
Some errors use a more specific code than the general one for their status, for example already_lead, email_required or wrong_employee. Treat any code you don't recognise by its HTTP status.
Validation errors
A 422 lists every field that failed in details. loc is the path to the field (body, then the keys inside your JSON), msg says what is wrong:
{
"error": {
"code": "validation_error",
"message": "The request is invalid.",
"details": [
{
"loc": ["body", "contact", "phone"],
"msg": "Value error, Enter a valid mobile number, like 98765 43210.",
"type": "value_error"
},
{
"loc": ["body", "facts", "business_type"],
"msg": "Extra inputs are not permitted",
"type": "extra_forbidden"
}
]
}
}facts, are checked strictly: a field the endpoint doesn't know is an error, not ignored. This catches typos (budjet_inr) before they lose data. Send only the documented fields.Rate limits
Each API key may make 300 requests a minute. Every response tells you where you stand:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the current minute. |
X-RateLimit-Remaining | Requests left in the current minute. |
X-RateLimit-Reset | Seconds until the minute resets. |
Retry-After | Only on 429: seconds to wait before trying again. |
The minute is a fixed window per key. When syncing a large list, spread requests out rather than sending them all at once, and on a 429 wait the Retry-After time before continuing.
Paging through lists
List endpoints take limit (how many to return) and offset (how many to skip), and answer with the page and the total:
# Leads 51–100, newest first
curl "https://progz.in/api/v1/leads?limit=50&offset=50" \
-H "Authorization: Bearer $PROGZ_API_KEY"{ "items": [ … ], "total": 128, "limit": 50, "offset": 50 }Keep asking with offset increased by limit until offset reaches total. The largest limit differs per endpoint (up to 200 for leads); asking for more gets a 422.
Data formats
| Kind | Format | Example |
|---|---|---|
| Ids | UUID | 3f6c2a1e-8b4d-4c1a-9e2f-5d7b8a9c0e11 |
| Times | ISO 8601. We answer in UTC; send any offset. | 2026-10-28T10:00:00+05:30 |
| Phone numbers | Send Indian mobiles with or without +91 (spaces and dashes are fine); other countries with + and the country code. We answer in international format. | 98765 43210 → +919876543210 |
| Money | Whole rupees in fields ending _inr. | "budget_inr": 6500000 |
| Durations | Whole days in fields ending _days. | "purchase_timeline_days": 60 |
| Languages | Language and region, as in te-IN. | te-IN, hi-IN, en-IN |