Headers

• Commune-Version string(date)

  The contract version this request is written against, as a release date (YYYY-MM-DD). Omitting the header pins the request to the version that was current when the API key was issued, so an integration keeps working when a newer version ships. An unknown value answers 400 with invalid_version.

Responses

• 200 application/json

  The current window, limit and remaining for this key.

  Hide response attributes Show response attributes object

  • object string Required

    Always rate_limit.

    Value is rate_limit.

  • limit integer Required

    The general budget's limit, repeated for convenience.

    Minimum value is 1.

  • remaining integer Required

    Requests left on the general budget in this window.

    Minimum value is 0.

  • window_seconds integer Required

    The general budget's window length.

    Minimum value is 1.

  • reset_at string(date-time) Required

    When the general budget's window resets.

  • policies array[object] Required

    Every budget this key is measured against, general first. A budget that does not apply to any operation the key may call is still listed, because what it counts is a property of the API rather than of the key.

    Hide policies attributes Show policies attributes object

    One budget a key is measured against. A request is charged to every budget that applies to its operation, and has to pass all of them.

    • name string Required

      general counts every request made with the key. audience counts only the operations that return subscriber or recipient email addresses, and is the tighter of the two.

      Values are general or audience.

    • limit integer Required

      Requests this budget allows per window.

      Minimum value is 1.

    • used integer Required

      Requests counted in the current window, including the one that asked.

      Minimum value is 0.

    • remaining integer Required

      Requests left in the current window. Zero means the next request charged to this budget answers 429.

      Minimum value is 0.

    • window_seconds integer Required

      How long a window lasts. A window is anchored to the first request that opened it rather than to the clock, so it does not reset on the minute.

      Minimum value is 1.

    • reset_at string(date-time) Required

      When this budget's window resets and used returns to zero. The same instant RateLimit-Reset reports as a number of seconds.

    • description string Required

      What this budget counts, in one line.

• 401 application/json

  No API key was presented, or the key is unknown, revoked or expired.

  All four answer identically, down to the wording. Saying that a key was revoked rather than never issued confirms to whoever is holding the string that it was once real, which a legitimate caller does not need and a thief should not get.

  Hide headers attribute Show headers attribute

  • WWW-Authenticate string

    The authentication scheme this API accepts. Always Bearer realm="Commune API"; there is no second scheme and no query-parameter fallback, because a credential that can travel in a URL ends up in access logs and referer headers.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.

• 429 application/json

  Too many requests. Back off and retry after the interval named by the Retry-After response header.

  Hide headers attribute Show headers attribute

  • Retry-After integer

    Seconds to wait before retrying.

    Minimum value is 1.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.

• 500 application/json

  Something failed inside Commune. The request may be retried.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.