Skip to content

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.

Response 409
{
  "error": {
    "code": "already_lead",
    "message": "This person is already a lead for this offering.",
    "details": null
  }
}
StatuscodeWhat happenedWhat to do
400bad_requestThe request can't be done as sent.Read the message; fix the request.
401invalid_api_keyThe key is unknown, revoked or expired, or its creator left the business.Check the key; create a new one if needed.
401api_key_not_allowedThis endpoint needs a person signed in.Do it in the app instead.
403permission_deniedThe key's role can't do this.Use a key with a higher role.
404not_foundNo such record in this business (or the URL is wrong).Check the id and the path.
409conflictIt clashes with what already exists, e.g. already_lead, contact_archived.Don't retry as is; use the existing record.
409call_waitingThe 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.
422validation_errorA field is missing, has the wrong type, or isn't allowed.Fix the fields listed in details.
429rate_limitedToo many requests this minute.Wait Retry-After seconds, then retry.
500internal_errorSomething failed on our side.Retry with backoff; contact us if it lasts.
503service_unavailableA 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:

Response 422
{
  "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"
      }
    ]
  }
}
Unknown fields are rejected
Lead and candidate bodies, and their 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:

HeaderMeaning
X-RateLimit-LimitRequests allowed in the current minute.
X-RateLimit-RemainingRequests left in the current minute.
X-RateLimit-ResetSeconds until the minute resets.
Retry-AfterOnly 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:

Request
# Leads 51–100, newest first
curl "https://progz.in/api/v1/leads?limit=50&offset=50" \
  -H "Authorization: Bearer $PROGZ_API_KEY"
Response 200
{ "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

KindFormatExample
IdsUUID3f6c2a1e-8b4d-4c1a-9e2f-5d7b8a9c0e11
TimesISO 8601. We answer in UTC; send any offset.2026-10-28T10:00:00+05:30
Phone numbersSend 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
MoneyWhole rupees in fields ending _inr."budget_inr": 6500000
DurationsWhole days in fields ending _days."purchase_timeline_days": 60
LanguagesLanguage and region, as in te-IN.te-IN, hi-IN, en-IN