Errors & Retries

GAINS Connect reports every outcome with a standard HTTP status and, for errors, a JSON body that says what went wrong. Use this page to read an error response, to decide whether to fix the request or retry it, and to choose the Idempotency-Key for a resend.

Read an error response

Most errors return a single Reason:

{
  "Reason": "The field 'ItemCod' is not recognized. Please ensure you are using the correct field names and try again."
}

Some responses carry a different body:

When	Body
Several fields fail validation at once	`Reasons`, an array of messages, instead of `Reason`.
An unexpected server error (`500`)	`error_id` and `Reason`. Quote the `error_id` to support. Some `500` responses carry only a `Reason`.
An endpoint needs a newer GAINS X version (`426`)	The installed and required GAINS X versions.
A submit rejects some or all records (`207`, `422`)	The rejected records and why. See Rejected Records.

{
  "Reasons": [
    "Gap must be at least 1 minute",
    "PayloadMaxItems must be greater than 0"
  ]
}

{
  "error_id": "3f0b7c52-9a1e-4d6b-8e2f-5c4a1b7d9e03",
  "Reason": "We encountered an unexpected issue. Please report this to [email protected] and reference error ID 3f0b7c52-9a1e-4d6b-8e2f-5c4a1b7d9e03"
}

Branch on the status code, not on the text of Reason. The text explains the problem to a person and can change between releases.

Status codes

Status	Meaning
`200 OK`	The request succeeded.
`202 Accepted`	A submit passed validation and was queued as a task. Follow it with `GET /tasks/{TaskId}`.
`204 No Content`	Nothing to return, for example no webhook settings yet.
`207 Multi-Status`	A submit was partly accepted: the valid records were queued, the rejected ones are listed.
`400 Bad Request`	The request is malformed, for example invalid JSON, an unknown field or a value of the wrong type, or it repeats an `Idempotency-Key`.
`401 Unauthorized`	Credentials are missing, expired or invalid, GAINS refused the Basic user name or password, or a partner endpoint received Basic credentials. See Authentication.
`403 Forbidden`	Your credentials are valid but not for this endpoint, or the service is not part of your environment.
`404 Not Found`	The path does not exist, or it names something that does not exist, such as a webhook.
`405 Method Not Allowed`	The endpoint does not accept this HTTP method.
`415 Unsupported Media Type`	`Content-Type` is missing or is not `application/json`.
`422 Unprocessable Content`	A submit accepted no records: every record failed validation, the array was empty, or it held more records than a submit accepts.
`424 Failed Dependency`	A custom route is configured but not ready yet. Retry later.
`426 Upgrade Required`	The endpoint needs a newer GAINS X than your environment runs; see When your version is too old (426).
`429 Too Many Requests`	GAINS Connect is still taking in earlier submits and did not accept this one. Retry after `Retry-After`; see Load Throughput & Retries.
`500 Internal Server Error`	An unexpected error. Report the `error_id` when the body carries one.
`503 Service Unavailable`	GAINS cannot be reached, is in its daily maintenance window, returned an error, or loads are not enabled for your environment, or the authentication service is unavailable during a Basic login; see GAINS Versions & Availability.
`504 Gateway Timeout`	GAINS did not answer in time; see GAINS cannot be reached.

The API Reference lists, for each endpoint, the statuses it documents.

Decide whether to retry

Match the status code first. For a 403 or a 503, also match the Reason: different ones need different actions.

Response	Retry?
No response, or the connection dropped	Yes, after a delay.
`400` `The idempotency key indicates a duplicate payload.`	Not yet: the first request may have been accepted. See Idempotency.
Any other `400`, and `404`, `405`, `415`, `422`	No. Fix the request first.
`401`	After you correct the credentials or request a new token.
`403`	No. Request a token with access to this route, or contact your GAINS representative if the service is not part of your environment.
`424`	Yes, later. The custom route is not ready yet; see Custom Schema.
`426`	No. Upgrade GAINS X; see When your version is too old.
`429`	Yes, the same request, after the `Retry-After` interval; see Load Throughput & Retries.
`500`	Once, after a delay. If it fails again, report the `error_id`.
`503` daily maintenance	Yes, every few minutes until the window ends. Submits are not affected.
`503` GAINS cannot be reached, or `GainsX returned an internal error`	Yes, after a delay.
`503` `Authentication service is currently unavailable.`	Yes, after a delay.
`503` `This feature is not configured for your environment.`	No. Ask your GAINS representative to enable loads.
Any other `503`	No. Contact your GAINS representative.
`504`	Yes, after a delay.

How long to wait between attempts, and when to stop, is in Load Throughput & Retries.

Which key to resend with

When you resend a submit, the Idempotency-Key depends on what the first attempt received:

First attempt received	Resend with
`429`, or no response at all	The same key. After a `429` nothing was saved and the key was released; with no response you cannot tell whether the first request was accepted, and the same key stops it being loaded twice.
Any other error response	A new key. Nothing from the request was saved, and the key may already be recorded, so resending under it would be refused as a duplicate.
`400` `The idempotency key indicates a duplicate payload.`	Nothing yet. Check whether the first attempt was accepted, as Idempotency describes.

Once you change the records, always use a new key. How keys work is in Idempotency.

Authentication: 401 and 403 in detail
GAINS Versions & Availability: 426, 503 and 504 in detail
Idempotency: how keys work and how to check a duplicate
Load Throughput & Retries: the 429 backlog and pacing submits
Rejected Records: reading 207 and 422

Read an error response

Status codes

Decide whether to retry

Which key to resend with

Related