API Status Code Guide

CAFE24 API uses standard HTTP status codes to indicate the results of API requests. Check the meanings of each status code and how to respond below.

✅ Success Responses (2xx)

200 OK

Indicates that GET, PUT, DELETE requests have been processed successfully.

Cases:

GET retrieval request success
PUT update request success
DELETE deletion request success

Example:

curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json'

Response Example:

{
  "resource": {
    "product_no": 128,
    "product_name": "Sample Product",
    "price": 10000
  }
}

201 Created

Indicates that a new resource has been successfully created via POST request.

Cases:

Product registration
Order creation
Category addition

Example:

curl -X POST 'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_name": "New Product",
    "price": 15000
  }'

207 Multi-Status

Returned when processing multiple requests and each object has different status.

Cases:

When registering multiple products simultaneously and only some succeed
Partial failure during batch update

How to Resolve: Check the status code for each object and respond according to that status.

Response Example:

{
  "resource": [
    {
      "product_no": 101,
      "status": 201,
      "message": "Created successfully"
    },
    {
      "product_no": 102,
      "status": 400,
      "message": "Invalid parameter"
    }
  ]
}

❌ Client Errors (4xx)

400 Bad Request

The server cannot understand the request.

Cases:

Content-Type Error
- Content-Type is incorrectly specified
- application/type is not json
Encoding Error
- Korean or special characters in API URL are not encoded

How to Resolve:

# ❌ Incorrect example
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/products?name=상품'

# ✅ Correct example
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/products?name=%EC%83%81%ED%92%88'

Check Items:

Verify Content-Type: application/json header
Verify URL parameter encoding

401 Unauthorized

Authentication information is missing or invalid.

Cases:

Access Token Not Provided
- Missing Authorization header
Access Token Invalid
- Wrong token
- Expired token
- Unknown client
When Using Front API
- client_id not entered

How to Resolve:

Admin API:

# ✅ Correct authentication method
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json'

Front API:

# ✅ Front API uses client_id
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/products' \
  -H 'X-Cafe24-Client-Id: {client_id}' \
  -H 'Content-Type: application/json'

Check Items:

Whether a valid Access Token is issued
Check Token expiration time
Using correct authentication method (Admin API vs Front API)

403 Forbidden

Authenticated but no permission to access the resource.

Cases:

Insufficient Scope Permission
- Access Token exists but no permission for that Scope
HTTPS Not Used
- Request made via HTTP
New Product Mall Not Upgraded
- Using old product management system
App Deleted
- App has been deleted from shopping mall

How to Resolve:

Check API permissions

# If Scope permission is required, issue a new token
# Check app permission settings in Developer Center

Use HTTPS

# ❌ Incorrect example
curl -X GET 'http://{mallid}.cafe24api.com/api/v2/admin/products'

# ✅ Correct example
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products'

Reinstall app
- If app was deleted from shopping mall, reinstall it

404 Not Found

The requested resource cannot be found.

Cases:

Incorrect URL
- Endpoint error
- Resource path error
Resource Does Not Exist
- Non-existent product number
- Non-existent order number
Missing ID
- {#id} value is missing

How to Resolve:

# Check correct endpoint in API documentation
# Example: GET /api/v2/admin/products/{product_no}

# ❌ Incorrect example
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/prodcuts' # typo

# ✅ Correct example
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products/128'

409 Conflict

Attempting to duplicate update the same resource with the same content.

Cases:

PUT request without changed data

How to Resolve:

# Please provide data to be modified
# Modify to send only data with changes

422 Unprocessable Entity

Request data differs from spec or is invalid.

Cases:

Missing Required Parameters
- Required fields left empty
Invalid Values
- Wrong data type
- Out of range values
- Values not matching specified spec

How to Resolve:

# Check required parameters in API documentation
curl -X POST 'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_name": "Sample Product",      # Required
    "price": 10000,                        # Required
    "supply_price": 5000,                  # Required
    "category_no": 1                       # Required
  }'

Check Items:

Whether required parameters are included
Whether data types match
Value validity verification

429 Too Many Requests

API request exceeded Rate Limit.

Cases:

Bucket exceeded (excessive momentary requests)
Maximum allowed API request count exceeded

Rate Limit Policy:

Admin API (Leaky Bucket):

Bucket fills up to the set call count limit per shopping mall
Bucket decreases by 2 per second
No restrictions if called 2 times or less per second

D.Collection API:

Maximum 40 times per minute per IP

How to Resolve:

# Check Rate Limit header
# Monitor X-Api-Call-Limit and adjust requests
# Example: X-Api-Call-Limit: 1/40

# Solution: Retry after a moment
# Or adjust request rate

Best Practices:

// Example: Rate Limit handling in Node.js
const makeRequest = async (url) => {
  try {
    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    });

    // Check Rate Limit header
    const remaining = response.headers.get('X-Api-Call-Limit');
    if (!remaining) {
      // Rate limit reached, retry needed
      await delay(1000);
      return makeRequest(url);
    }

    return response.json();
  } catch (error) {
    console.error('API Error:', error);
  }
};

🔴 Server Errors (5xx)

500 Internal Server Error

Internal server error has occurred.

Cases:

Unknown server error
Temporary error

How to Resolve:

Please try again after a moment
If it persists, contact Developer Center

503 Service Unavailable

Server is currently down or unavailable.

Cases:

Server maintenance
Server down

How to Resolve:

API unavailable
Wait for server recovery
Contact Developer Center

504 Gateway Timeout

Request processing time has exceeded.

Cases:

Response timeout
Temporary network delay

How to Resolve:

# Please try again after a moment
# If persistent Timeout occurs, review request structure

📊 Error Response Format

All API errors are returned in the following JSON format:

{
  "error": {
    "code": "error_code",
    "message": "error message",
    "more_info": {
      // Additional information
    }
  }
}

Header	Description
`X-Api-Call-Limit`	Current API call status (current/limit)
`X-Cafe24-Call-Usage`	Call usage rate (%) against limit
`X-Cafe24-Call-Remain`	Remaining time (seconds) until call resumption
`X-Cafe24-Time-Usage`	Processing time usage rate (%) against limit
`X-Cafe24-Time-Remain`	Remaining time (seconds) until processing time resumption

Cafe24 Analytics API Headers

Header	Description
`X-RateLimit-Remaining`	Remaining Token count
`X-RateLimit-Requested-Tokens`	Requested Token count
`X-RateLimit-Burst-Capacity`	Maximum Bucket capacity
`X-RateLimit-Replenish-Rate`	Token replenishment rate per second

💡 Best Practices

1. Pre-Request Checklist

✅ Check Authorization header
✅ Check Content-Type: application/json
✅ Check HTTPS usage
✅ Check URL parameter encoding
✅ Check required parameters inclusion

2. Error Handling Strategy

// Retry logic (Exponential Backoff)
const retryWithBackoff = async (fn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

3. Rate Limit Management

Monitor Rate Limit information in Response header
Adjust request rate
Distributed processing for batch requests

✅ Success Responses (2xx)​

200 OK​

201 Created​

207 Multi-Status​

❌ Client Errors (4xx)​

400 Bad Request​

401 Unauthorized​

403 Forbidden​

404 Not Found​

409 Conflict​

422 Unprocessable Entity​

429 Too Many Requests​

🔴 Server Errors (5xx)​

500 Internal Server Error​

503 Service Unavailable​

504 Gateway Timeout​

📊 Error Response Format​

🔗 Related Headers​

Rate Limit Related Headers​

Cafe24 Analytics API Headers​

💡 Best Practices​

1. Pre-Request Checklist​

2. Error Handling Strategy​

3. Rate Limit Management​

📚 References​

✅ Success Responses (2xx)

200 OK

201 Created

207 Multi-Status

❌ Client Errors (4xx)

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable Entity

429 Too Many Requests

🔴 Server Errors (5xx)

500 Internal Server Error

503 Service Unavailable

504 Gateway Timeout

📊 Error Response Format

🔗 Related Headers

Rate Limit Related Headers

Cafe24 Analytics API Headers

💡 Best Practices

1. Pre-Request Checklist

2. Error Handling Strategy

3. Rate Limit Management

📚 References