Errors and limits
Every error the Twotic gateway can return, what causes it, whether you were charged, and how rate limiting and automatic refunds work.
Errors are always JSON, with an error code and a human-readable message that names what went wrong.
Gateway status codes
| Status | Code | Cause | Charged? |
|---|---|---|---|
| 401 | unauthorized | Missing, malformed or revoked key | No |
| 402 | insufficient_funds | The call costs more than your balance | No |
| 403 | not_subscribed | Valid key, but not subscribed to this API | No |
| 404 | api_not_found | No published API at that slug | No |
| 404 | endpoint_not_found | That method and path are not an endpoint of this API | No |
| 429 | rate_limited | Per-minute ceiling exceeded | No |
| 5xx | internal_error | A failure on our side | Not charged |
Rate limits
Each API sets its own per-minute ceiling, applied per key. Every response carries the current state:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 41
X-RateLimit-Reset: 1735689600A 429 also carries Retry-After in seconds. The window is fixed rather than sliding, so the counter resets on the minute boundary.
What you are not charged for
Any failure on our side is not charged, and that is applied automatically — you do not need to ask. The response reports a cost of zero and your usage log agrees.
A 4xx is charged. It is a real answer about a malformed request, and producing it took the same work as a successful call. The message always states what was wrong.
Running out of credit
Calls return 402 with your balance and the cost of the call. Nothing is deleted, no keys are revoked, and no subscriptions lapse. Top up and the same key resumes working on the next request.