Conventions, errors and limits
The request and response shapes, every error code, and the rate limits.
Conventions
- Base URL
https://easycoexistence.com/api/v1, HTTPS only. Every request carriesAuthorization: Bearer ec_live_…; bodies are JSON withContent-Type: application/json. - Fields are snake_case, dates are ISO 8601 in UTC, ids are UUIDs (connect sessions start with
cs_). - A list answers
{ "data": [ … ] }; one resource answers the object itself. - New fields and events are added over time without notice: ignore the ones you do not use. Breaking changes would come as a new version path.
- The same file as OpenAPI 3.1, for Postman, client generators and coding agents; and as text for AI tools.
Errors
Errors share one shape. Branch on code; the message is for people and may change.
{
"error": {
"code": "not_found",
"message": "No connection with that id on this account."
}
}Error codes
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_json | The body is not valid JSON. |
| 400 | invalid_request | A field is missing or wrong; the message names it. |
| 400, 409 | channel_unavailable | That channel cannot be used for this: not one this account can connect, or one that cannot post. |
| 400 | not_supported | The network sends no events to relay. |
| 400 | invalid_media | The file could not be fetched, is too large, or is not a type the network takes. |
| 401 | unauthorized | No key, or a key that does not exist or was revoked. |
| 402 | billing_required | This needs an active subscription. Reading always works. |
| 402 | suspended | The number or channel is suspended because the subscription ended. Reconnect it. |
| 404 | not_found | Nothing with that id on this account. |
| 409 | removed | It was removed from the account. |
| 409 | conflict | The post can no longer be changed or canceled. |
| 409 | not_managed | Forwarding needs the number to be managed first. |
| 409 | secret_change | The events URL is already set: send replace_secret: true. |
| 429 | rate_limited | Too many requests; the message says when to retry. |
| 500 | internal | Our side failed. Retry; tell support if it keeps happening. |
| 502 | meta_error | Meta failed while we talked to it. Retry. |
| 502 | meta_rejected | Meta refused the change; the message is Meta's. |
| 502 | revoke_failed | Meta did not release the number, so nothing changed. It is retried on our side. |
| 502 | credentials_unavailable | The network would not give a fresh token; the channel may need connecting again. |
Limits
- 30 failed authentications per IP in 15 minutes, then
429. - Connect sessions: 50 open and 100 created per hour per account.
- Automation tests: 60 an hour.
- Other requests have no fixed cap; be reasonable, and prefer events to polling a number every few seconds.
- Meta's own limits apply to sending: 20 messages per second per coexistence number, and the 24-hour window.