Error Handling

When working with the Artos Store API, it's important to understand the different types of errors that might occur and how to handle them effectively. This guide covers the error responses from the API, including status codes, error formats, and recommendations for troubleshooting.

Error Response Format

All API errors follow a consistent format, making it easier to handle them programmatically:

Every error response includes:

A status code that identifies the type of error
An error message that explains what went wrong
A unique error code (when applicable)
Sometimes additional details to help troubleshoot the issue

This standardized format allows you to create consistent error handling across your application.

Error response structure

{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid product data. Price must be a positive number.",
  "code": "INVALID_PRODUCT_DATA",
  "details": {
    "fieldErrors": {
      "price": "Must be greater than 0"
    }
  }
}

HTTP Status Codes

The Artos Store API uses standard HTTP status codes to indicate the success or failure of API requests. Here are the main categories:

Name
2xx
Description
Success codes that indicate the request was successful.
Name
4xx
Description
Client error codes that indicate an issue with your request.
Name
5xx
Description
Server error codes that indicate an issue on the Artos server.

Client Error Codes (4xx)

400 Bad Request

A 400 Bad Request error indicates that the server cannot process your request due to client-side errors such as:

Invalid JSON format
Missing required fields
Invalid field values
Validation errors

To resolve this error, check your request data carefully and ensure it matches the API requirements specified in the documentation.

400 Bad Request Example

{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid request data",
  "code": "VALIDATION_ERROR",
  "details": {
    "fieldErrors": {
      "name": "Product name is required",
      "price": "Price must be a number greater than zero"
    }
  }
}

401 Unauthorized

A 401 Unauthorized error occurs when your request lacks valid authentication credentials. This typically happens when:

Your store ID is invalid or missing
Your authentication token has expired (in future authentication systems)
You're trying to access resources without proper authentication

To resolve this error, ensure you're including the correct store ID in your requests.

401 Unauthorized Example

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Store not found or access denied",
  "code": "STORE_ACCESS_DENIED"
}

403 Forbidden

A 403 Forbidden error indicates that the server understood your request but refuses to authorize it. This differs from 401 in that authentication is not the issue, but rather permissions:

You're authenticated correctly but don't have permission for the requested action
The resource exists but is restricted from your access level
The operation is not allowed in the current context

This error typically requires checking your permission levels or contacting support if you believe you should have access.

403 Forbidden Example

{
  "status": 403,
  "error": "Forbidden",
  "message": "You do not have permission to delete this product",
  "code": "PERMISSION_DENIED"
}

404 Not Found

A 404 Not Found error occurs when the requested resource doesn't exist:

The URL is incorrect
The resource has been deleted
The resource ID is invalid
The resource exists but is in another store

To resolve this error, verify that the resource ID and endpoint are correct.

404 Not Found Example

{
  "status": 404,
  "error": "Not Found",
  "message": "Product with ID '12345' not found",
  "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

A 409 Conflict error indicates that the request couldn't be completed due to a conflict with the current state of the resource. This typically occurs when:

You're trying to create a resource that already exists
You're attempting to modify a resource that has been modified by another request
The operation violates a business rule or constraint

To resolve this error, you may need to retrieve the latest version of the resource before making changes, or use a different identifier for new resources.

409 Conflict Example

{
  "status": 409,
  "error": "Conflict",
  "message": "A product with SKU 'ABC123' already exists",
  "code": "DUPLICATE_RESOURCE",
  "details": {
    "conflictingId": "existing-product-id"
  }
}

429 Too Many Requests

A 429 Too Many Requests error occurs when you've exceeded the rate limits for the API. The Artos Store API implements rate limiting to ensure fair usage and system stability.

When you receive this error, the response will include headers that indicate:

How many requests you have remaining
When your quota will reset

To resolve this error, implement exponential backoff in your application and reduce the frequency of your API calls.

429 Too Many Requests Example

{
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again in 30 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Server Error Codes (5xx)

500 Internal Server Error

A 500 Internal Server Error indicates that something went wrong on the Artos server. These errors are not related to your request but rather to issues on our end.

When you receive a 500 error:

The error is automatically logged on our systems
Our team is notified to investigate
You should retry the request after a short delay

If you consistently receive 500 errors for a specific request, please contact Artos support with details about your request to help us resolve the issue more quickly.

500 Internal Server Error Example

{
  "status": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred while processing your request",
  "code": "SERVER_ERROR",
}

503 Service Unavailable

A 503 Service Unavailable error indicates that the Artos API is temporarily unavailable, typically due to:

Scheduled maintenance
Temporary overload
System updates

These errors are usually brief. The response may include a Retry-After header indicating when to retry your request.

503 Service Unavailable Example

{
  "status": 503,
  "error": "Service Unavailable",
  "message": "The API is currently undergoing maintenance. Please try again later.",
  "code": "SERVICE_UNAVAILABLE"
}

Pagination Products