GAINS Version Requirements & Availability

GAINS Connect works with your GAINS environment on every call, so what it can do depends on the GAINS version you run and on whether GAINS is available at that moment. This page explains which endpoints need a minimum GAINS X version, how to check yours, and what the 426, 503 and related responses mean when GAINS cannot serve a request.

Check your GAINS 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": "10.0-ER2610",
      "Status": "success"
    }
  }
}

The full response is described in Check your connection.

Version requirements

Some endpoints need a minimum GAINS X version, because they rely on something GAINS added in that release. The endpoint's API Reference page states it at the end of its description, under GainsX Version Requirement: for example, GET /replenishment/production-orders needs 10.0-ER2610. A Min line gives the oldest supported version; a Max line, when present, gives the newest.

Some webhook features also need a later version. Saving a webhook configuration that uses one is refused with a message naming the version it needs.

When your version is too old (426)

An endpoint whose requirement your GAINS X does not meet answers 426 without doing anything:

{
  "StatusMessage": "Endpoint requires GAINSX 10.0-ER2610 or higher",
  "GainsXCurrentVersion": "10.0-ER2609",
  "GainsXMinimumVersion": "10.0-ER2610"
}

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 loads, 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 load 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. Do not retry; ask your GAINS representative to enable loads.

Service not available (403)

A service that is not part of your subscription answers 403 with a Reason saying it is not available on this environment. Contact your GAINS representative if you have signed up for the service.

GAINS cannot be reached

When GAINS cannot be reached, GAINS Connect answers 503:

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

When GAINS is reached but does not answer in time, it answers 504, after a noticeable delay:

{
  "Reason": "The GAINS service did not respond in time. Please try again later or contact support if the issue continues."
}

Retry either one after a delay. Services.GAINSX.Status in GET /ping shows failed for as long as GAINS cannot be reached.

What to do

Before you retry a load, see Retry safely for which Idempotency-Key to send. For statuses not listed here, see Errors Handling & Exceptions.

Related

• Getting Started
• Errors Handling & Exceptions
• Idempotency
• Webhooks