Error Handling

All errors should be returned as enveloped responses. The API gateway should make limited-to-no changes to error messages exposed by the underlying system.

Copy

Copied

{
    "error": {
        "code": "ERROR_CODE_IDENTIFIER",
        "message": "Description of the error."
    }
}

We recommend explicitly modeling the following error codes as follows:

400 INPUT_VALIDATION_FAILED - Moveworks submitted an invalid request to the gateway.

Copy

Copied

{
  "error": {
      "code": "INPUT_VALIDATION_FAILED",
      "message": "Mandatory field not provided: submitted_by."
  }
}

400 FORM_OUT_OF_DATE - Moveworks submitted a form which is no longer valid since it has been updated in the source system.

Copy

Copied

{
  "error": {
      "code": "FORM_OUT_OF_DATE",
      "message": "This form was last updated on 2022-10-20T07:00:00Z which is after the ingestion metadata date (2022-10-19T07:00:00Z)"
  }
}

If you surface this error code, Moveworks will gracefully handle it by linking your employees to the latest version of the form. See example below:

Out-of-date error

401 AUTHENTICATION_FAILED - The provided credential by Moveworks is invalid or missing. This is NOT the same as authentication failing between the gateway and your downstream systems.

Copy

Copied

{
  "error": {
      "code": "AUTHENTICATION_FAILED",
      "message": "Bearer token missing.",
  }
}

404 NOT_FOUND - The resource (form) Moveworks is requesting for is missing.

Copy

Copied

{
  "error": {
      "code": "NOT_FOUND",
      "message": "Form ID 222 does not exist.",
  }
}

429 RATE_LIMIT_EXCEEDED - Moveworks has exceeded the allowable # of requests / min.

Copy

Copied

{
  "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded.",
  }
}

All responses should continue the following headers indicating rate limit consumption:

Copy

Copied

X-RateLimit-Limit: 600 # The maximum number of requests you're permitted to make per minute.
X-RateLimit-Remaining: 421 # The number of requests remaining in the current rate limit window.
X-RateLimit-Reset: 18 # The remaining window before the rate limit FULLY resets in UTC epoch seconds.

502 EXTERNAL_REST_ERROR - Something went wrong between the gateway and your system. Should include the raw response from the source system's error.

Copy

Copied

{
  "error": {
      "code": "EXTERNAL_REST_ERROR",
      "message": "Service Cloud rejected the request. Raw response: SOQL insertion failed. Can not set Case Owner to Contact record.",
  }
}

500 INTERNAL_SERVER_ERROR - Something went wrong in the gateway and threw an exception.

Copy

Copied

{
  "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "message": "NoneType has no attribute 'records'",
  }
}