GAINS Versions & Availability

GAINS Connect works with your GAINS X environment on every call, so what it can do depends on the GAINS X version you run and on whether GAINS X is available at that moment. This page explains how version requirements work, how to check your version, and why GAINS Connect answers 426, 503 or 504 when GAINS X cannot serve a request. Whether to retry each status, and with which Idempotency-Key, is in Errors & Retries.

Check your GAINS X version

Call GET /ping. It needs no credentials, and Services.GAINSX reports the GAINS X version installed and whether GAINS Connect can reach it:

{
  "Services": {
    "GAINSX": {
      "Version": "<installed GAINS X version>",
      "Status": "success"
    }
  }
}

Version requirements

Every endpoint except GET /ping and the lead-time prediction endpoints needs a minimum GAINS X version. Most need only the oldest version GAINS Connect supports; some need a later one, because they rely on something GAINS X added in that release. The endpoint's API Reference page states its requirement at the end of its description, under GainsX Version Requirement. A Min line gives the oldest supported version; a Max line, when present, gives the newest.

Some webhook features also need a later GAINS X version. Saving a webhook configuration that uses one is refused with 400 and a message naming the version it needs: upgrade GAINS X, or save the configuration without that feature.

When your version is too old (426)

An endpoint whose requirement your GAINS X does not meet answers 426 without doing anything. The body names the version you run and the version the endpoint needs:

{
  "StatusMessage": "Endpoint requires GAINSX <minimum version> or higher",
  "GainsXCurrentVersion": "<installed version>",
  "GainsXMinimumVersion": "<minimum version>"
}

When the endpoint also has a maximum, StatusMessage reads Endpoint requires GAINSX version between <min> and <max> and the body adds GainsXMaximumVersion. When GAINS X does not report its version, GainsXCurrentVersion is unknown.

Retrying does not help. Ask your GAINS representative about upgrading GAINS X.

Daily maintenance window

GAINS runs daily processing during which its planning data cannot be read. For as long as it lasts, every endpoint except submits, GET /ping and the lead-time prediction endpoints answers 503:

{
  "Reason": "The API is unavailable due to daily maintenance window activities. Please retry after maintenance is complete."
}

Retry every few minutes until the window ends. Your GAINS representative can tell you when it usually runs, so that you can schedule reads outside it.

Loads not enabled (503)

When your environment is not set up to accept loads, every submit and delete endpoint answers 503:

{
  "Reason": "This feature is not configured for your environment. Please contact your GAINS representative."
}

Config.InboundEndpoints in the GET /ping response is false in this case. Ask your GAINS representative to enable loads.

Service not available (403)

A service that is not part of your subscription answers 403:

{
  "Reason": "The Gains X service is not available on this environment. Please connect with your GAINS representative if you have signed up."
}

GAINS cannot be reached

When GAINS X cannot be reached, GAINS Connect answers 503. When GAINS X is reached but does not answer in time, it answers 504, which can take several minutes. Both carry the same body:

{
  "Reason": "The Gains service is currently unavailable. Please try again later or contact support if the issue continues."
}

Services.GAINSX.Status in GET /ping shows failed for as long as GAINS X cannot be reached.

GAINS returned an error (503)

When GAINS X is reached but answers with an error, GAINS Connect answers 503. If GAINS X is failing temporarily, the Reason asks you to try again later:

{
  "Reason": "GainsX returned an internal error (500). The service may be temporarily unavailable. Please try again later or contact support if the issue continues."
}

Any other 503 from GAINS X asks you to contact your GAINS administrator; retrying does not help.

Changes within v1

Every endpoint is under /api/v1. A GAINS Connect release can change the API within v1 in these ways, listed in the Changelog:

• New fields in responses and webhook payloads. Ignore fields you do not recognise rather than failing on them. Requests work the other way: GAINS Connect refuses a field it does not know, see Unknown fields are refused.
• New endpoints, webhook triggers and optional request fields.
• Stricter validation of a value that was previously accepted.

Related

• Errors & Retries: whether to retry each status, and with which key
• Getting Started: the full ping response
• Configuring Webhooks: webhook features that need a later GAINS X
• Changelog: what each release changed