Error Catalog

Understand error responses and how to handle them.

HTTP Status Codes

Status Meaning Action
200 OK Request succeeded Process the response body
201 Created Resource created successfully Process the response body (the created resource)
400 Bad Request Invalid request (missing fields, invalid values) Check the error response for details and fix the request
401 Unauthorized Missing or invalid authentication token Request a new access token and retry
403 Forbidden Valid token but insufficient permissions Contact support to verify your permissions
404 Not Found The requested resource does not exist Verify the external code or identifier
409 Conflict Resource already exists (duplicate external code) Use PUT to update the existing resource, or use a different external code
500 Internal Server Error Server-side error Retry after a delay. If persistent, contact support

Error Response Structure

When the API returns a 4xx or 5xx error, the response body contains a structured error object:

JSON Error Response
{
  "entityName": "product",
  "errorKey": "nonExistingProduct",
  "type": "https://www.jhipster.tech/problem/problem-with-message",
  "title": "Product does not exist for passed id!",
  "status": "404",
  "message": "error.nonExistingProduct",
  "params": "product"
}

Error Response Fields

Field Type Description
entityName string The type of entity that caused the error (e.g., document, product)
errorKey string Machine-readable error identifier. Use this for programmatic error handling
type string Error type URI (RFC 7807 Problem Details)
title string Human-readable error description
status string HTTP status code
message string Internal error message key
params string Additional context (the entity type or parameter that caused the error)

Business Error Types

These are the most common business errors you may encounter. Use the errorKey field to identify and handle each error type programmatically.

Error Key HTTP Status Entity Description
nonExistingProduct 404 product The product with the given external code does not exist. Create the product first.
nonExistingLot 404 lot The specified lot code does not exist for this product.
nonExistingReception 404 reception The reception with the given external code does not exist.
nonExistingShippingOrder 404 shippingOrder The shipping order with the given code does not exist.
nonExistingPacking 404 packing No packing data found for the given document code.
nonExistingWarehouse 404 warehouse The specified warehouse does not exist.
shippingOrderInvalidStatus 400 shippingOrder The shipping order is in a status that does not allow the requested operation (e.g., already closed or cancelled).

Handling Errors

Recommended Error Handling Pattern

Python
import requests

response = requests.post(
    "https://app.logistics-wms.com/api/external/v1/document",
    headers={"Authorization": f"Bearer {token}"},
    json=document_payload
)

if response.status_code == 201:
    document = response.json()
    print(f"Document created: {document['externalCode']}")

elif response.status_code == 401:
    # Token expired - refresh and retry
    token = refresh_access_token()
    # Retry the request...

elif response.status_code in (400, 404, 409):
    error = response.json()
    error_key = error.get("errorKey", "unknown")

    if error_key == "nonExistingProduct":
        # Create the product first, then retry
        create_product(...)
    else:
        log.error(f"API error: {error_key} - {error.get('title')}")

elif response.status_code >= 500:
    # Server error - retry with exponential backoff
    retry_with_backoff(...)
Best practices for error handling
  • Always check the errorKey field for programmatic decisions, not the title (which may change)
  • Implement automatic token refresh when you receive a 401
  • Use exponential backoff for retries on 5xx errors
  • Log the full error response for debugging
  • Do not retry 400 errors without fixing the request payload first