Problems

Errors from the API are returned in the form of a Problem, conforming to RFC 7807.

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.

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 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:

{
  "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 for more information. Wait before retrying your request; you can inspect the rate limit headers to determine when tokens will be available.