> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/go-v2/developer-integration/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

<Accordion title="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.

  ```json theme={null}
  {
    "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.
</Accordion>