Skip to content

Errors and rate limits

The Pinlyx API answers in JSON. A successful call returns a 2xx status with the resource; a failed call returns a 4xx or 5xx status, and in most cases a small error object that says what went wrong.

CodeMeaningWhen it happens
200OKThe request succeeded.
201CreatedA resource was created, for example POST /v1/contacts.
202AcceptedWork was queued for the background worker, for example POST /v1/telegram/messages.
207Multi-StatusPOST /v1/contacts/batch finished with some rows failed or skipped. Check each row’s status.
400Bad RequestThe body or a query parameter failed validation.
401UnauthorizedThe bearer token is missing, malformed, revoked or expired. The body is empty.
402Payment RequiredYour plan does not include the feature behind this endpoint.
403ForbiddenThe key lacks the scope the endpoint needs, or your workspace role does not allow writes.
404Not FoundThe resource does not exist or is outside the key’s workspace.
409ConflictThe write clashes with existing data (for example a duplicate externalId) or an Idempotency-Key was reused.
429Too Many RequestsThe key used up its per-minute budget. See Rate limits.
5xxServer errorSomething failed on our side. Safe to retry with backoff.

Validation, not found, conflict and permission errors share one envelope:

FieldDescription
ErrorMachine-readable code, for example bad_request, not_found, conflict, forbidden, payment_required.
MessageA human-readable explanation.
DetailsExtra context when there is any, otherwise null.
{
"Error": "bad_request",
"Message": "text is required",
"Details": null
}

Two errors come from earlier in the request pipeline and use lowercase keys instead:

{
"error": "insufficient_scope",
"message": "This endpoint requires one of: contacts:write",
"requiredScopes": ["contacts:write"]
}
{
"error": "rate_limit_exceeded",
"message": "Per-minute request budget exhausted for this API key"
}

POST /v1/contacts, POST /v1/contacts/batch and POST /v1/social/posts accept an Idempotency-Key header. Send a unique string (up to 255 characters) with the request; if you retry with the same key and the same body within 24 hours, the API returns the first response again instead of writing twice, and sets Idempotency-Replayed: true. The same key with a different body returns 409.

Each API key has its own request budget per minute, shared between the REST API and the MCP server. A new key allows 60 requests per minute. Every authenticated response carries:

HeaderDescription
X-RateLimit-LimitRequests this key may make per minute.
X-RateLimit-RemainingRequests left in the current window.
X-RateLimit-ResetUnix time (seconds) when the window resets.

When the budget runs out, the API returns 429 with the rate_limit_exceeded body above and a Retry-After header giving the seconds to wait.