# Error Codes

This page documents the various error responses you may encounter when calling the CONNECT Authenticate API.

## Failed Service Requests

Not providing a username or password will receive a **401 Unauthorized** HTTP Status.

Rate Limiting
Rate limiting is implemented on the Authenticate endpoint to ensure fair usage and to protect the service from excessive requests.

- Up to **5 identical invalid requests** are permitted within a **2-minute period**
- Upon reaching this limit, any further identical requests will receive a **429 HTTP Status (Too Many Requests)**
- There is also a threshold for the total number of authentication requests allowed within a **5-minute window**


Important: Avoid Automated Retries
We **strongly recommend** that integrations avoid repeating automated identical invalid authorization requests. Instead, catch an unauthorized response and terminate the processing.

Violating this recommendation and reaching the threshold will result in a **lockout of the endpoint**. If this occurs, you will need to wait **5 minutes** before the endpoint will accept new requests.

To protect our customer base from the effects of misuse of the Authorization endpoint, Creditsafe may **block a customer account or IP address** if too many calls using invalid credentials are identified.

## Error Response Codes

| HTTP Status Code | Response Body |
|  --- | --- |
| **400** Bad Request | *(Empty or minimal error message)* |
| **401** Unauthorized | Access denied - Please check that your username and password are correct. Please be aware that usernames and passwords are case sensitive. If the problem persists, please contact your Creditsafe account manager. |
| **429** Too Many Requests | Too many identical requests within a 2-minute period or total amount of requests exceeded |


## Common Problems and Solutions

The most common problems to look for when authorization fails are:

| Problem | Solution |
|  --- | --- |
| **Unauthorized** | Credentials are case sensitive. Has the password changed? |
| **Email based username is provided instead of the user key** | Make sure to always use **User Key** as username when authorizing to API's. Email addresses will not work. |
| **Customer or user is not active in the Creditsafe system** | Check with Creditsafe integration support |
| **The user has been locked out due to too many bad authorization attempts in a row** | Wait 2 minutes until the user is unlocked again |
| **The user was recently linked to an Identity with one or more other users, leaving the users with different passwords** | Check with Creditsafe integration support. If this problem is assumed, ask for a reset of the Identity password. Please note that this would change passwords for all users linked to that Identity |


## Token Expired Error (403)

When an **expired token** is used in a service call (not the authenticate endpoint itself), a **403 HTTP Status (Token Expired)** response will be returned.

This indicates that your token has exceeded its 1-hour lifetime and needs to be refreshed.

**Recommended Solutions:**

1. Catch the 403 Token Expired response and refresh the token when needed
2. Track token generation time and proactively refresh approximately 55 minutes after generation


Contact Support
If you continue to experience authentication issues, contact the Creditsafe Integration team at **[integration@creditsafe.se](mailto:integration@creditsafe.se)**

Indicates that rate limits have been exceeded.

| Code | Text | Detail | Solution |
|  --- | --- | --- | --- |
| 429 | Too many requests | Rate limit exceeded | Wait before retrying, implement exponential backoff |


**Example:**


```json
{
  "error": {
    "code": "429",
    "text": "Too many requests",
    "detail": "Rate limit exceeded. Please wait before retrying."
  }
}
```

### 500 Internal Server Error

Indicates an unexpected error occurred on the server.

| Code | Text | Detail | Solution |
|  --- | --- | --- | --- |
| 500 | Internal server error | An unexpected error occurred | Try again later. If the issue persists, contact [integration@creditsafe.se](mailto:integration@creditsafe.se) with the timestamp and error details |


**Example:**


```json
{
  "error": {
    "code": "500",
    "text": "Internal server error",
    "detail": "An unexpected error occurred. Please try again later."
  }
}
```

## Troubleshooting Tips

1. **Invalid Credentials (401)**
  - Verify username and password are exactly as provided by Creditsafe
  - Check for extra spaces or hidden characters
  - Remember that credentials are case-sensitive
2. **Account Issues (401/403)**
  - Confirm your account has been activated
  - Check if you've completed the welcome email setup process
  - Contact [integration@creditsafe.se](mailto:integration@creditsafe.se) if account issues persist
3. **Rate Limiting (429)**
  - Implement token caching to reduce authentication requests
  - Add exponential backoff retry logic
  - Reuse tokens across multiple API calls
4. **Service Issues (500)**
  - Check Creditsafe service status
  - Retry after a brief delay
  - Contact support if issues persist beyond 15 minutes


Need Help?
For any authentication issues that cannot be resolved using this documentation, please contact the Integration team at **[integration@creditsafe.se](mailto:integration@creditsafe.se)** with:

- The timestamp of the failed request
- The full error response received
- Your username (never send your password)