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.
Status codes
Section titled “Status codes”| Code | Meaning | When it happens |
|---|---|---|
200 | OK | The request succeeded. |
201 | Created | A resource was created, for example POST /v1/contacts. |
202 | Accepted | Work was queued for the background worker, for example POST /v1/telegram/messages. |
207 | Multi-Status | POST /v1/contacts/batch finished with some rows failed or skipped. Check each row’s status. |
400 | Bad Request | The body or a query parameter failed validation. |
401 | Unauthorized | The bearer token is missing, malformed, revoked or expired. The body is empty. |
402 | Payment Required | Your plan does not include the feature behind this endpoint. |
403 | Forbidden | The key lacks the scope the endpoint needs, or your workspace role does not allow writes. |
404 | Not Found | The resource does not exist or is outside the key’s workspace. |
409 | Conflict | The write clashes with existing data (for example a duplicate externalId) or an Idempotency-Key was reused. |
429 | Too Many Requests | The key used up its per-minute budget. See Rate limits. |
5xx | Server error | Something failed on our side. Safe to retry with backoff. |
Error body
Section titled “Error body”Validation, not found, conflict and permission errors share one envelope:
| Field | Description |
|---|---|
Error | Machine-readable code, for example bad_request, not_found, conflict, forbidden, payment_required. |
Message | A human-readable explanation. |
Details | Extra 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"}Retry writes safely
Section titled “Retry writes safely”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.
Rate limits
Section titled “Rate limits”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:
| Header | Description |
|---|---|
X-RateLimit-Limit | Requests this key may make per minute. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | Unix 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.