Errors

Two surfaces return errors, and they use different formats.

• The token endpoint, POST /oauth/token, returns OAuth 2.0 error bodies (error and error_description).
• The integration management endpoints under /api/v2/integrations use the standard Flavours envelope (meta and data) described on the Errors page.

Token endpoint

An error body has an error code and an error_description. Some also carry a hint. Branch your code on the HTTP status and the error code, not on the description text.

Invalid client or secret

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

A missing client_secret returns the same response.

Wrong or missing grant type

{
  "error": "unsupported_grant_type",
  "error_description": "The authorization grant type is not supported by the authorization server.",
  "hint": "Check that all required parameters have been provided"
}

Only client_credentials is supported. Other grants, such as password, return this response.

Missing client ID

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.",
  "hint": "Check the `client_id` parameter"
}

Rate limit

The token endpoint allows 10 requests per minute for each client_id and 30 requests per minute for each IP address. Every attempt counts, including failed ones. Every token response carries X-RateLimit-Limit and X-RateLimit-Remaining. When you exceed a limit, the endpoint returns 429 with a Retry-After header and the standard envelope:

{
  "meta": {
    "code": 429,
    "status": "error",
    "message": "Too many token requests. Please try again shortly."
  },
  "data": null
}

See Rate limiting for the headers.

Integration management

You create, edit, rotate, and revoke integrations in the Flavours web app, which calls these endpoints with your signed-in session. The errors below are what the web app surfaces. All use the standard envelope.

The password rule on create and rotate has a 10-minute window: after a correct password, further create and rotate requests by the same user need no password for 10 minutes. Edit, revoke, and list never ask for it.

An admin account that has no market of its own must also send market_id; otherwise the response is 422 with field set to market.

Example 403 for a missing password:

{
  "meta": {
    "code": 403,
    "status": "error",
    "message": "Please confirm your password to create an integration."
  },
  "data": {
    "reason": "PASSWORD_REQUIRED"
  }
}

Example 422 for a duplicate name:

{
  "meta": {
    "code": 422,
    "status": "error",
    "message": "An integration with this name already exists."
  },
  "data": null
}