# Problems

Errors from the API are returned in the form of a Problem, conforming to [RFC 7807](https://tools.ietf.org/html/rfc7807).

If you receive a 4xx or 5xx error with the `Content-Type` header set to `application/problem+json`, the body of the response will contain a Problem object.

You can use the `type` field to programmatically determine which error you are receiving.

## Problem Object Structure

All problems share these common fields:

| Field | Type | Description |
|  --- | --- | --- |
| `type` | `string` | A URI that identifies the problem type. |
| `title` | `string` | A short, human-readable summary of the problem. |
| `status` | `int` | The HTTP status code for this problem. |
| `detail` | `string` | A human-readable explanation specific to this occurrence of the problem. May not always be present. |


Some problem types include additional fields. These are documented in the reference below.

## Reference

### Unauthorized

| Field | Value |
|  --- | --- |
| **Type** | `https://docs.bright.hr/problems#unauthorized` |
| **Status** | `401` |
| **Title** | Unauthorized |


Returned when the request lacks valid authentication credentials. Ensure you are including a valid bearer token in the `Authorization` header. See [Authentication](/gettingstarted#2-obtain-a-bearer-token).

### Token Expired

| Field | Value |
|  --- | --- |
| **Type** | `https://docs.bright.hr/problems#token-expired` |
| **Status** | `401` |
| **Title** | Token Expired |


Returned when the bearer token provided in the request has expired. Obtain a new token by repeating the [authentication](/gettingstarted#2-obtain-a-bearer-token) process.

### Invalid Token

| Field | Value |
|  --- | --- |
| **Type** | `https://docs.bright.hr/problems#invalid-token` |
| **Status** | `401` |
| **Title** | Invalid Token |


Returned when the bearer token provided in the request is malformed or otherwise invalid.

### Forbidden

| Field | Value |
|  --- | --- |
| **Type** | `https://docs.bright.hr/problems#forbidden` |
| **Status** | `403` |
| **Title** | Forbidden |


Returned when the authenticated application does not have permission to perform the requested operation.

### Resource Not Found

| Field | Value |
|  --- | --- |
| **Type** | `https://docs.bright.hr/problems#resource-not-found` |
| **Status** | `404` |
| **Title** | Resource Not Found |


Returned when the endpoint is valid but the specific resource referenced in the request does not exist. For example, requesting an employee by an ID that does not belong to your organisation.

### Conflict

| Field | Value |
|  --- | --- |
| **Type** | `https://docs.bright.hr/problems#conflict` |
| **Status** | `409` |
| **Title** | Conflict |


Returned when the request could not be completed because it conflicts with another concurrent operation on the same resource. Retry the request after a short delay.

### Field Validation

| Field | Value |
|  --- | --- |
| **Type** | `https://docs.bright.hr/problems#field-validation` |
| **Status** | `422` |
| **Title** | Validation Failed |


Returned when one or more fields in the request are invalid. The response includes an additional `errors` field containing the validation failures.

**Additional fields:**

| Field | Type | Description |
|  --- | --- | --- |
| `errors` | `object<string, string[]>` | A map of field names to an array of validation error messages for that field. |


**Example response:**


```json
{
  "type": "https://docs.bright.hr/problems#field-validation",
  "title": "Validation Failed",
  "status": 422,
  "detail": "Inspect the `errors` field for the set of validation errors.",
  "errors": {
    "pageSize": ["The field PageSize must be between 1 and 100."]
  }
}
```

### Rate Limited

| Field | Value |
|  --- | --- |
| **Type** | `https://docs.bright.hr/problems#rate-limited` |
| **Status** | `429` |
| **Title** | Too Many Requests |


Returned when you have exceeded the API rate limit. See [Rate Limits](/rate-limit) for more information. Wait before retrying your request; you can inspect the rate limit headers to determine when tokens will be available.