Skip to content
Last updated

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:

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

Response Fields

FieldTypeDescription
codeintegerUnique error identifier
descriptionstringHuman-readable error description
detailsobjectAdditional error-specific information (optional)

Common Errors (1000-1099)

CodeHTTP StatusDescriptionResolution
1001400Error while parsing payloadCheck request body syntax and content type
1002400Validation errorVerify request data meets validation rules
1003400Parameter errorCheck request parameters are correct

Authentication Errors (2000-2099)

CodeHTTP StatusDescriptionResolution
2001401UnauthorizedProvide valid authentication credentials
2002403ForbiddenCheck user permissions and access rights
2003400User have not any organization please contact to supportContact support to assign organization
2004401Invalid credentialsVerify username and password are correct
2005400Invalid organization type. Please contact supportContact support for organization type issues

Location Errors (3000-3099)

CodeHTTP StatusDescriptionResolution
3001404Location not foundCheck location ID or search for valid location
3002400Invalid location queryVerify location query parameters are correct

Search Errors (4000-4099)

CodeHTTP StatusDescriptionResolution
4002400Invalid product codeVerify product code format and availability
4003400Invalid search IDUse valid search ID from search results
4004404Product not foundCheck product ID or search for available products
4005400Invalid check-in timeUse valid future date for check-in
4006400Invalid check-out timeUse valid future date for check-out
4007400Invalid reservation periodEnsure check-out is after check-in date
4008400Invalid commissionCheck commission value meets requirements
4009400Office suppliers are differentUse offices from the same supplier
4010400Invalid currency codeUse valid ISO 4217 currency code

Order Errors (5000-5099)

CodeHTTP StatusDescriptionResolution
5001404Agency configuration not found. Some configurations may not be set up yet. Please contact support.Contact support for agency configuration
5002404Order not foundVerify order ID is correct
5003400Organization has not primary billing addressAdd primary billing address to organization
5004400Agency can not add individual billing addressUse corporate billing address for agency orders
5005400Order is not open. It may be closed or cancelled.Check order status before modification
5006400Order item does not belong to orderVerify order item belongs to the specified order
5007400Order has no paymentAdd payment information to the order
5008404Item not foundVerify item ID is correct
5009400Item status is not validCheck item status allows the requested operation
5010400Passenger identity number is invalidProvide valid identity number format
5011400Passenger passport number is invalidProvide valid passport number format
5012500Reservation failedRetry reservation or contact support
5013400Order cannot be canceledCheck order status allows cancellation
5014400Product quantity is invalidUse valid quantity within allowed limits
5015400Invalid product codeUse valid product code from available products
5016400Passenger birth date is invalidProvide valid birth date format
5017400Limited credit not allowedAgency is not authorized for limited credit
5018400Full credit not allowedAgency is not authorized for full credit

Payment Errors (6000-6099)

CodeHTTP StatusDescriptionResolution
6001400No credit limit found requested currencySet up credit limit for the requested currency
6002400Payment failedCheck payment details and try again
6003400Invalid payment typeUse supported payment type (credit card or limit)
6004400Car is already reservedSelect a different vehicle or time slot
6005400Invalid card informationVerify credit card details are correct
6006400Invalid installment countSelect valid installment option

Error Handling Best Practices

Client Implementation

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

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

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:

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