Get started
Errors & limits
Every failure has the same body: { "code", "message" }. The code is stable to build on; the message is for people.
Error codes
| Status | Code | Meaning |
|---|---|---|
| 400 | BAD_REQUESTMalformed request: bad ids, dates or ranges, an unknown metric or time zone, a write body that does not fit, or an Idempotency-Key already used for a different request. The message says which. | Malformed request: bad ids, dates or ranges, an unknown metric or time zone, a write body that does not fit, or an Idempotency-Key already used for a different request. The message says which. |
| 401 | UNAUTHORIZEDMissing, invalid, or revoked API key. | Missing, invalid, or revoked API key. |
| 402 | SUBSCRIPTION_INACTIVEYou own this server, but cormac+ is not active on it. | You own this server, but cormac+ is not active on it. |
| 403 | FORBIDDEN_SCOPEThe key wasn't given the scope this endpoint needs, or wasn't given this server. | The key wasn't given the scope this endpoint needs, or wasn't given this server. |
| 404 | NOT_FOUNDNot your server, not a member of it, or really not there. | Not your server, not a member of it, or really not there. |
| 405 | METHOD_NOT_ALLOWEDThe path exists, but not for this method. Allow lists the ones it takes. | The path exists, but not for this method. Allow lists the ones it takes. |
| 409 | PLUGIN_DISABLEDThe plugin behind this endpoint is turned off on that server. | The plugin behind this endpoint is turned off on that server. |
| 409 | IDEMPOTENCY_CONFLICTA write with the same Idempotency-Key is still running. Retry once it has finished. | A write with the same Idempotency-Key is still running. Retry once it has finished. |
| 429 | RATE_LIMITEDOver the limit. Retry-After says when to come back. | Over the limit. Retry-After says when to come back. |
| 503 | UPSTREAM_UNAVAILABLEcormac itself can't be reached. Retry with backoff. A write that fails this way may or may not have gone through, so check before you retry it. | cormac itself can't be reached. Retry with backoff. A write that fails this way may or may not have gone through, so check before you retry it. |
Rate limits
60 requests a minute and 10,000 a day, per key. Writes also count against their own limit of 30 a minute, and the headers describe whichever limit is closest. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 adds Retry-After.