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

# Error handling

> Best practices on handling errors and other exceptions.

In some situations, the API may return an error. In general, errors can be classified as either server-side or client-side errors.

## Client errors

In case of a badly formatted API request, the API returns an
error with an HTTP status code in the 400 to 499 range.

Based on the type of client error made, the response is one of the
following.

* `400` **Bad request** - Returned when the request passed authentication and authorization checks, but the request did not have the data it expected. In most situations, this is because of missing request properties, or incorrect values for properties.
* `401` **Unauthorized** - Returned when the bearer token was not valid and could not be used to authorize the API call. In this case please check the [List 4XX errors](/reference/logs/list-api-error-logs) API to inspect the cause of the issue.
* `403` **Forbidden** - Returned when the bearer token is valid but the authenticating client does not have permission to access or manipulate the resource. This may be due to insufficient scopes in the JWT, a restricted API key used to sign the JWT, or a resource being locked.
* `404` **Not found** - The resource could not be found. In a small number of cases, the resource may indeed exist, but due to permissions it is not accessible to the authenticated client and returning a `403` would provide information that should not be available to the caller.
* `405` **Method not allowed** - The HTTP method used was not recognized for the path of the request.
* `409` **Duplicate record** - A record already exists that matches one of the unique constrain for this resource. Check the API documentation for the call made to check what fields have a unique constraint.

<CodeGroup>
  ```json 400 theme={"system"}
  {
    "type": "error", 
    "code": "bad_request",
    "status": 400,
    "message": "Request failed validation",
    "details": [
      {
        "type": "type_error.uuid",
        "pointer": "/payment_method/buyer_id",
        "message": "value is not a valid uuid",
        "location": "body"
      }
    ]
  }
  ```

  ```json 401 theme={"system"}
  {
      "type": "error",
      "code": "unauthorized",
      "status": 401,
      "message": "No valid API authentication found",
      "details": []
  }
  ```

  ```json 403 theme={"system"}
  {
      "type": "error",
      "code": "forbidden",
      "status": 403,
      "message": "Invalid credentials",
      "details": []
  }
  ```

  ```json 404 theme={"system"}
  {
      "type": "error",
      "code": "not_found",
      "status": 404,
      "message": "The resource could not be found",
      "details": []
  }
  ```

  ```json 405 theme={"system"}
  {
      "type": "error",
      "code": "method_not_allowed",
      "status": 409,
      "message": "Method Not Allowed",
      "details": []
  }
  ```

  ```json 409 theme={"system"}
  {
      "type": "error",
      "code": "duplicate_record",
      "status": 409,
      "message": "Duplicate record",
      "details": []
  }
  ```
</CodeGroup>

The [API reference](/reference/errors/client-errors) has more detail on the format of client errors. The [List 4XX errors](/reference/logs/list-api-error-logs) API can be used to see the latest client errors and the associated requests.

## Server errors

In case of a server-side error in the system, the API returns an
error with an HTTP status code in the 500 to 599 range.

None of these errors can be resolved client side. Please contact support to raise any `5XX` errors.

<CodeGroup>
  ```json 500 theme={"system"}
  {
      "type": "error",
      "code": "server_error",
      "status": 500,
      "message": "Request could not be processed",
      "details": []
  }
  ```

  ```json 502 theme={"system"}
  {
      "type": "error",
      "code": "bad_gateway",
      "status": 502,
      "message": "Request could not be processed",
      "details": []
  }
  ```

  ```json 504 theme={"system"}
  {
      "type": "error",
      "code": "gateway_timeout",
      "status": 504,
      "message": "Request could not be processed",
      "details": []
  }
  ```
</CodeGroup>

The [API reference](/reference/errors/server-errors) has more detail on the format of server errors.