CommPeak API Error Codes, Rate Limits, and Troubleshooting

Every CommPeak API is served over HTTPS and returns JSON. This page covers the conventions that differ between APIs, the status codes you can get back, the most common first-request errors, and the rate limits to plan for before you go to production.

Request and response format

Send Content-Type: application/json with every request that has a body. Some conventions differ by API:

Dialer API and PBX API: filter, order, page, and select fields with URL path segments, for example /calls/campaign_id/42/limit/50;0. Dates use ISO 8601 format in UTC. For details, see Core API Concepts.
Portal API, Dialer API, PBX API, and Lookup API: a request that fails validation returns 422 with a JSON body that describes the field at fault.
Lookup API: you can submit bulk lookups as a list of numbers or as a file upload.
PBX Stats API (deprecated): most endpoints, including those that only retrieve data, use POST.

Phone number format

Formats differ by endpoint, so check the parameter description on the endpoint's page. Most endpoints take international format with the country code, for example 447700900123.

Handling errors

CommPeak APIs use standard HTTP status codes to report the result of a request.

Status code	Meaning	What to do
`200`, `201`, `204`	The request succeeded.	No action is needed.
`400`	The request is malformed or missing required data.	Check the parameters and the request body.
`401`, `403`	The credentials are missing or invalid, or the request comes from an IP address that is not allowed, or the key's access settings do not allow the request, for example Full access (all services) is off.	Check your key, the `Authorization` header, the IP ACL, and the key's access settings.
`402`	Your balance is depleted (TextPeak APIs).	Top up your balance. Retrying does not help until you do.
`404`	The resource does not exist, or the endpoint is served on your own subdomain.	Check the ID or path in the URL, and any `url` field in the response.
`422`	A parameter or field failed validation.	Fix the field named in the response body.
`429`	You sent too many requests in a short time.	Wait, then retry with an increasing delay.
`5XX`	An unexpected or temporary error occurred on the server.	Retry later. If the error persists, contact CommPeak support.

🚧
WARNING
TextPeak messaging and OTP endpoints can return HTTP 200 with "status": false for some validation errors. Always check the status field in the response body, not only the HTTP status code. For the full list of error codes, see the TextPeak API overview.

Troubleshooting your first request

Most first-request errors come from the key, the header, or the address. Find your symptom in the table and try the fix.

Symptom	Likely cause	Fix
`403` with `{"detail":"Not authenticated"}`	The `Authorization` header is missing.	Add `Authorization: <API_KEY>` to the request.
`401` or `403` from `api.commpeak.com`	The key is wrong or was deleted, or the request comes from an IP address outside the key's IP ACL.	Copy the key again from the API Keys tab and check its IP ACL.
The Portal API works, but the Dialer, PBX, or Lookup API returns `403`	Full access (all services) is off for the key.	Edit the key and turn on Full access (all services).
`404` with a `url` field	The endpoint is served on your own subdomain, not through `api.commpeak.com`.	Send the request to the address in the `url` field. See Endpoints you call on your own subdomain.
Authentication error on every TextPeak request	The token is sent with a `Bearer` prefix.	Send the token as the raw header value: `Authorization: <token>`.
Authentication error when sending a TextPeak message	The request uses the wrong token type, such as your API key instead of a stream token.	Get a stream token with your API key and send messages with it.
The Add API key button is unavailable in the CommPeak Portal	Your customer account is not fully activated yet.	Wait for activation, or contact your account manager.
`429`	You exceeded the rate limit.	Wait, then retry with an increasing delay. See Rate limits.

Rate limits

Rate limits protect the platform and differ by API:

Portal, Dialer, PBX, and Lookup APIs: api.commpeak.com allows about 10 requests per second. Requests over the limit return 429.
TextPeak APIs: sending is limited per stream by messages per second and per day, and OTP requests and failed verifications are limited per recipient.

To avoid hitting the limits, use endpoints that accept or return multiple records in a single request instead of sending one request per record.

Webhooks and callbacks

Some integrations work in the other direction: CommPeak sends data to your server when something happens, or your systems push data to CommPeak as it changes.

TextPeak webhooks send delivery and event callbacks to your endpoint. See Webhooks.
Dispatch Automation pushes leads into CommPeak Dialer from your CRM or other systems. See Dispatch Leads.
Speech recognition callbacks send Dialer and PBX speech recognition results to a callback URL you provide. See Send Speech with callback URL.

Versioning

Build your integration to ignore response fields it does not recognize, because new fields can appear in responses. In the TextPeak APIs, changes are backward compatible where possible, and breaking changes are released under a new version.