Response Codes

General response and error codes

GBG GO APIs use conventional HTTP response codes to indicate the success or failure of an API request.

Code	Description	Notes
200	Ok	Request successful
201	Created	New resource created successfully
400	Bad request	Request invalid or missing required parameters
401	Unauthorized	No valid authentication token or token expired
403	Forbidden	No permission to access the requested resource
404	Not found	Requested resource or endpoint does not exist
405	Method not allowed	HTTP method used, for example, GET or POST, is not supported
500	Internal server error	A problem with the API, which may not be related to your request server
503	Service unavailable	API 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.

Code	Description	Notes
1001	NOT_FOUND	Requested resource does not exist in Path, returned with HTTP 404
2001	UNAUTHORIZED	No valid authentication in Authorization, returned with HTTP 401
2002	FORBIDDEN	No permission for the resource in Authorization, returned with HTTP 403
4002	MISSING_FIELD	A required field is missing in Body, returned with HTTP 400
4003	INVALID_FIELD	A field conflicts with the current state in Body, returned with HTTP 409
4004	UNPROCESSABLE_ENTITY	The request body could not be processed in Body, returned with HTTP 422
4004	INVALID_FILTER	A query filter is invalid in Body, returned with HTTP 422
5001	UNKNOWN	An unexpected internal error occurred in Service, returned with HTTP 500
5005	SERVICE_UNAVAILABLE	The service is temporarily unavailable in Service, returned with HTTP 503

FAQ

How do I get granular failure reasons for document verification?

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"
    }
  ]
}

Field	Description
code	Numeric error code (returned as a string).
name	Machine-readable error identifier (for example, MISSING_FIELD).
location	Where the error originated: Body, Authorization, Path, or Service.
problem	A description of what went wrong.
action	What 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.