# Error Codes

This page contains comprehensive error codes and their descriptions that the Yolcu360 Agency API can return. Each error
code includes the HTTP status code, detailed description, and recommended actions for resolution.

## Error Response Format

When an error occurs, the API returns a consistent error response format:


```json
{
  "code": 1001,
  "description": "Error while parsing payload",
  "details": {
    "field": "checkInDateTime",
    "message": "Must be a future date",
    "value": "2023-01-01T10:00:00Z"
  }
}
```

### Response Fields

| Field | Type | Description |
|  --- | --- | --- |
| `code` | integer | Unique error identifier |
| `description` | string | Human-readable error description |
| `details` | object | Additional error-specific information (optional) |


## Common Errors (1000-1099)

| Code | HTTP Status | Description | Resolution |
|  --- | --- | --- | --- |
| 1001 | 400 | Error while parsing payload | Check request body syntax and content type |
| 1002 | 400 | Validation error | Verify request data meets validation rules |
| 1003 | 400 | Parameter error | Check request parameters are correct |


## Authentication Errors (2000-2099)

| Code | HTTP Status | Description | Resolution |
|  --- | --- | --- | --- |
| 2001 | 401 | Unauthorized | Provide valid authentication credentials |
| 2002 | 403 | Forbidden | Check user permissions and access rights |
| 2003 | 400 | User have not any organization please contact to support | Contact support to assign organization |
| 2004 | 401 | Invalid credentials | Verify username and password are correct |
| 2005 | 400 | Invalid organization type. Please contact support | Contact support for organization type issues |


## Location Errors (3000-3099)

| Code | HTTP Status | Description | Resolution |
|  --- | --- | --- | --- |
| 3001 | 404 | Location not found | Check location ID or search for valid location |
| 3002 | 400 | Invalid location query | Verify location query parameters are correct |


## Search Errors (4000-4099)

| Code | HTTP Status | Description | Resolution |
|  --- | --- | --- | --- |
| 4002 | 400 | Invalid product code | Verify product code format and availability |
| 4003 | 400 | Invalid search ID | Use valid search ID from search results |
| 4004 | 404 | Product not found | Check product ID or search for available products |
| 4005 | 400 | Invalid check-in time | Use valid future date for check-in |
| 4006 | 400 | Invalid check-out time | Use valid future date for check-out |
| 4007 | 400 | Invalid reservation period | Ensure check-out is after check-in date |
| 4008 | 400 | Invalid commission | Check commission value meets requirements |
| 4009 | 400 | Office suppliers are different | Use offices from the same supplier |
| 4010 | 400 | Invalid currency code | Use valid ISO 4217 currency code |


## Order Errors (5000-5099)

| Code | HTTP Status | Description | Resolution |
|  --- | --- | --- | --- |
| 5001 | 404 | Agency configuration not found. Some configurations may not be set up yet. Please contact support. | Contact support for agency configuration |
| 5002 | 404 | Order not found | Verify order ID is correct |
| 5003 | 400 | Organization has not primary billing address | Add primary billing address to organization |
| 5004 | 400 | Agency can not add individual billing address | Use corporate billing address for agency orders |
| 5005 | 400 | Order is not open. It may be closed or cancelled. | Check order status before modification |
| 5006 | 400 | Order item does not belong to order | Verify order item belongs to the specified order |
| 5007 | 400 | Order has no payment | Add payment information to the order |
| 5008 | 404 | Item not found | Verify item ID is correct |
| 5009 | 400 | Item status is not valid | Check item status allows the requested operation |
| 5010 | 400 | Passenger identity number is invalid | Provide valid identity number format |
| 5011 | 400 | Passenger passport number is invalid | Provide valid passport number format |
| 5012 | 500 | Reservation failed | Retry reservation or contact support |
| 5013 | 400 | Order cannot be canceled | Check order status allows cancellation |
| 5014 | 400 | Product quantity is invalid | Use valid quantity within allowed limits |
| 5015 | 400 | Invalid product code | Use valid product code from available products |
| 5016 | 400 | Passenger birth date is invalid | Provide valid birth date format |
| 5017 | 400 | Limited credit not allowed | Agency is not authorized for limited credit |
| 5018 | 400 | Full credit not allowed | Agency is not authorized for full credit |


## Payment Errors (6000-6099)

| Code | HTTP Status | Description | Resolution |
|  --- | --- | --- | --- |
| 6001 | 400 | No credit limit found requested currency | Set up credit limit for the requested currency |
| 6002 | 400 | Payment failed | Check payment details and try again |
| 6003 | 400 | Invalid payment type | Use supported payment type (credit card or limit) |
| 6004 | 400 | Car is already reserved | Select a different vehicle or time slot |
| 6005 | 400 | Invalid card information | Verify credit card details are correct |
| 6006 | 400 | Invalid installment count | Select valid installment option |


## Error Handling Best Practices

### Client Implementation


```javascript
async function handleApiResponse(response) {
    if (!response.ok) {
        const error = await response.json();

        switch (error.code) {
            case 2001: // Unauthorized
                await refreshToken();
                return retryRequest();

            case 6002: // Payment failed
                showPaymentError('Payment failed. Please check your details and try again.');
                return;

            case 4004: // Product not found
                showSearchMessage('Product not found. Please try a different search.');
                return;

            case 1002: // Validation error
                showValidationError(error.description, error.details);
                return;

            default:
                showGenericError(error.description);
        }
    }

    return response.json();
}

function getRetryDelay(headers) {
    const retryAfter = headers.get('Retry-After');
    return retryAfter ? parseInt(retryAfter) * 1000 : 5000;
}
```

### Error Classification

#### Retriable Errors

- Reservation failed (5012)
- Network timeouts
- Service unavailability


#### Non-Retriable Errors

- Authentication errors (2001-2005)
- Validation errors (1001-1003)
- Not found errors (3001, 4001, 4004, 5002, 5008)
- Payment errors (6001-6006)


### Retry Strategy


```javascript
async function makeRequestWithRetry(url, options, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            const response = await fetch(url, options);

            if (response.ok) {
                return response;
            }

            if (!isRetriableError(response.status) || attempt === maxRetries) {
                throw new Error(`Request failed: ${response.status}`);
            }

            // Exponential backoff
            const delay = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
            await new Promise(resolve => setTimeout(resolve, delay));

        } catch (error) {
            if (attempt === maxRetries) {
                throw error;
            }
        }
    }
}

function isRetriableError(status, code) {
    // Check for specific error codes that are retriable
    if (code === 5012) return true; // Reservation failed

    // Check for HTTP status codes that are retriable
    return [500, 502, 503, 504].includes(status);
}
```

### Error Logging


```javascript
function logError(error, context) {
    const errorData = {
        timestamp: new Date().toISOString(),
        code: error.code,
        description: error.description,
        context: context,
        userAgent: navigator.userAgent,
        url: window.location.href
    };

    // Send to logging service
    fetch('/api/logs/error', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify(errorData)
    });

    // Log to console in development
    if (process.env.NODE_ENV === 'development') {
        console.error('API Error:', errorData);
    }
}
```

## Support and Troubleshooting

### Contact Information

For persistent errors or support:

- **Email**: api-support@yolcu360.com
- **Documentation**: [docs.yolcu360.com](https://docs.yolcu360.com)
- **Status Page**: [status.yolcu360.com](https://status.yolcu360.com)


### Required Information for Support

When contacting support, include:

1. Error code and description
2. Request timestamp
3. Request ID (if available in response headers)
4. Steps to reproduce
5. API key (last 4 characters only)


### Common Resolution Steps

1. **Check API Status**: Verify service status on status page
2. **Validate Request**: Ensure request format matches documentation
3. **Check Credentials**: Verify API key is active and has permissions
4. **Review Rate Limits**: Check if rate limits are exceeded
5. **Test Environment**: Try request in staging environment
6. **Update Integration**: Ensure using latest API version