Errors

The Price2b API uses conventional HTTP response codes and includes detailed error information to help you diagnose and fix issues quickly.

HTTP status codes

Code	Description
`200`	OK — Request succeeded (GET, PUT, PATCH)
`201`	Created — Resource created successfully (POST)
`204`	No Content — Request succeeded with no response body (DELETE)
`400`	Bad Request — Malformed request syntax
`401`	Unauthorized — Invalid or missing API token
`403`	Forbidden — Token lacks required permissions
`404`	Not Found — Resource doesn't exist
`422`	Unprocessable Entity — Validation error
`429`	Too Many Requests — Rate limit exceeded
`500`	Server Error — Something went wrong on our end

Error response format

All error responses follow a consistent JSON structure:

Error response

{
  "success": false,
  "message": "Human-readable error description",
  "error_code": "ERR_CODE",
  "errors": {
    "field_name": ["Specific validation error"]
  },
  "meta": {
    "additional": "context"
  }
}

Response fields

Name
success
Type
boolean
Description
Always false for error responses.
Name
message
Type
string
Description
A human-readable description of the error.
Name
error_code
Type
string
Description
A machine-readable error code for programmatic handling.
Name
errors
Type
object
Description
Field-specific validation errors (for 422 responses).
Name
meta
Type
object
Description
Additional context about the error (optional).

Authentication errors

AUTH_001 — Invalid or expired token

The provided API token is invalid, expired, or missing.

Solutions:

Check that the Authorization header is present
Verify the token format: Bearer {token}
Generate a new token if expired

Response

{
  "success": false,
  "message": "Unauthenticated.",
  "error_code": "AUTH_001"
}

AUTH_002 — Insufficient permissions

The authenticated user doesn't have access to this resource.

Solutions:

Verify your account has access to this area
Contact support to upgrade your plan

Response

{
  "success": false,
  "message": "You do not have permission to access this resource.",
  "error_code": "AUTH_002"
}

AUTH_003 — Token scope insufficient

The API token doesn't have the required scope.

Solutions:

Generate a new token with the required scope
Check which scope is needed in the endpoint documentation

Response

{
  "success": false,
  "message": "This action requires the 'shipping:write' scope.",
  "error_code": "AUTH_003"
}

Validation errors

VAL_001 — Validation failed

One or more fields failed validation.

Solutions:

Check the errors object for specific field issues
Verify required fields are present
Ensure data types match the specification

Response

{
  "success": false,
  "message": "The given data was invalid.",
  "error_code": "VAL_001",
  "errors": {
    "destination_country": ["The destination country must be a valid 2-letter ISO code."],
    "weight": ["The weight must be greater than 0."]
  }
}

Inventory errors

Code	Description
`INV_001`	Product not found
`INV_002`	Insufficient stock
`INV_003`	SKU already exists

INV_002 — Insufficient stock

The requested quantity exceeds available stock.

Response

{
  "success": false,
  "message": "Insufficient stock for product PROD-001",
  "error_code": "INV_002",
  "meta": {
    "product_id": 12345,
    "available_stock": 50,
    "requested_quantity": 100
  }
}

Shipping errors

Code	Description
`SHIP_001`	Quote expired
`SHIP_002`	Carrier unavailable
`SHIP_003`	Invalid address
`SHIP_004`	Label generation failed

SHIP_001 — Quote expired

The shipping quote has expired. Quotes are valid for 24 hours.

Response

{
  "success": false,
  "message": "This quote has expired. Please request a new quote.",
  "error_code": "SHIP_001",
  "meta": {
    "quote_id": "QT-2026-001234",
    "expired_at": "2026-01-30T23:59:59Z"
  }
}

SHIP_003 — Invalid address

The shipping address could not be validated by the carrier.

Response

{
  "success": false,
  "message": "The recipient address could not be validated.",
  "error_code": "SHIP_003",
  "errors": {
    "recipient.postal_code": ["Invalid postal code for the specified city."],
    "recipient.state": ["State does not match postal code."]
  }
}

Customs errors

Code	Description
`CUST_001`	HS code not found
`CUST_002`	Country not supported
`CUST_003`	Calculation failed

Order errors

Code	Description
`ORD_001`	Order not found
`ORD_002`	Order already shipped
`ORD_003`	Order cancelled

Fulfillment errors

Code	Description
`FUL_001`	Warehouse not available
`FUL_002`	Insufficient balance

Rate limit error

RATE_001 — Rate limit exceeded

You've exceeded the rate limit for this endpoint.

Solutions:

Wait for the retry_after period
Implement exponential backoff
Reduce request frequency

Response

{
  "success": false,
  "message": "Too many requests. Please retry after 60 seconds.",
  "error_code": "RATE_001",
  "retry_after": 60
}

Handling errors

Here's how to handle API errors gracefully in your application:

Error handling

async function apiRequest(endpoint, options = {}) {
  const response = await fetch(`https://app.price2b.com/api/v1${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${process.env.PRICE2B_TOKEN}`,
      'Accept': 'application/json',
      ...options.headers,
    },
  })

  const data = await response.json()

  if (!data.success) {
    switch (data.error_code) {
      case 'AUTH_001':
        throw new Error('Invalid API token')
      case 'RATE_001':
        await sleep(data.retry_after * 1000)
        return apiRequest(endpoint, options) // Retry
      case 'VAL_001':
        throw new ValidationError(data.errors)
      default:
        throw new Error(data.message)
    }
  }

  return data
}