Skip to main content
GBG GO APIs use conventional HTTP response codes to indicate the success or failure of an API request.
CodeDescriptionNotes
200OkRequest successful
201CreatedNew resource created successfully
400Bad requestRequest invalid or missing required parameters
401UnauthorizedNo valid authentication token or token expired
403ForbiddenNo permission to access the requested resource
404Not foundRequested resource or endpoint does not exist
405Method not allowedHTTP method used, for example, GET or POST, is not supported
500Internal server errorA problem with the API, which may not be related to your request server
503Service unavailableAPI service is temporarily down
For more details on API response codes and troubleshooting, refer to Error handling.

​
v2 error codes

In v2, errors also carry a GBG error code alongside the HTTP status. Each code maps to a named error and identifies where in the request the problem occurred.
CodeDescriptionNotes
1001NOT_FOUNDRequested resource does not exist in Path, returned with HTTP 404
2001UNAUTHORIZEDNo valid authentication in Authorization, returned with HTTP 401
2002FORBIDDENNo permission for the resource in Authorization, returned with HTTP 403
4002MISSING_FIELDA required field is missing in Body, returned with HTTP 400
4003INVALID_FIELDA field conflicts with the current state in Body, returned with HTTP 409
4004UNPROCESSABLE_ENTITYThe request body could not be processed in Body, returned with HTTP 422
4004INVALID_FILTERA query filter is invalid in Body, returned with HTTP 422
5001UNKNOWNAn unexpected internal error occurred in Service, returned with HTTP 500
5005SERVICE_UNAVAILABLEThe service is temporarily unavailable in Service, returned with HTTP 503

​
FAQ

You can access detailed failure reasons in two ways:
  • Through the v2 API error response
  • Through the Investigation portal.

​
v2 API error responses

The v2 API returns structured error objects that include a machine-readable error code, a description of the problem, and a recommended action. Each error specifies where the issue originated, making it easier to diagnose failures programmatically.
{
  "errors": [
    {
      "code": "4002",
      "name": "MISSING_FIELD",
      "location": "Body",
      "problem": "problem description goes here",
      "action": "action to resolve the issue goes here"
    }
  ]
}
FieldDescription
codeNumeric error code (returned as a string).
nameMachine-readable error identifier (for example, MISSING_FIELD).
locationWhere the error originated: Body, Authorization, Path, or Service.
problemA description of what went wrong.
actionWhat you should do to resolve the error.
Every API response also includes an X-Request-ID header. Include this value when contacting GBG support. It correlates your request with server-side logs for faster troubleshooting.

​
Investigation portal

For document-specific verification failures, the Investigation portal provides the most detailed view. To access granular failure reasons:
  1. Log in to the GBG GO platform and navigate to the Investigation section.
  2. Click the Session ID of the session you want to review. This opens the session detail view, which shows an overview of the session.
  3. Navigate to the Processing tab to see each module’s outcome, for example, Match, No Match, or Error.
  4. Expand any module section to see a breakdown of individual data point matches.
  5. Click More details to open the module detail view. The available tabs vary by module type.
  6. Check the Raw Response tab for the complete response from the verification provider, which contains the module errors and reasons.