Error Codes

This page describes the HTTP status codes and error response formats you may encounter when working with the pycli API. Understanding these codes helps you distinguish between client-side mistakes (such as missing required fields or invalid types) and server-side issues, so you can handle errors gracefully in your integration. Every endpoint in the pycli API follows consistent error conventions, making it straightforward to write robust error-handling logic once and apply it across all requests.

Before using this reference, make sure you have:

• A working pycli installation (see the Installation guide)
• A basic understanding of HTTP request/response cycles
• Familiarity with JSON request and response bodies
• An HTTP client (such as curl, httpie, or a library like requests in Python) to test API calls

To run the pycli API locally so you can observe error responses firsthand:

1. Install dependencies

   Copy

   pip install fastapi uvicorn
   

2. Start the API server

   Copy

   uvicorn api:app --reload
   

3. Confirm the server is running

   Copy

   curl http://localhost:8000/orders
   

   You should receive a 200 OK response with an empty orders list. If you receive a connection error, verify that port 8000 is not already in use.

The following request parameters influence how the API validates your input and what errors it returns:

Keeping these type contracts in mind lets you anticipate validation errors before making a request.

The pycli API returns standard HTTP status codes for every response. You should check the status code before attempting to parse the response body.

Successful responses always return a 2xx status code:

• 200 OK — The request succeeded. The response body contains the requested data.

Client error responses return a 4xx status code and signal that your request needs to be corrected:

• 422 Unprocessable Entity — The request body or path/query parameters failed validation. This is the most common error you will encounter. The response body contains a detail array describing exactly which fields are invalid and why.
• 404 Not Found — The requested resource (such as an order ID) does not exist. (Returned by the framework for unregistered routes.)
• 405 Method Not Allowed — You used an HTTP method the endpoint does not support.

Server error responses return a 5xx status code and indicate an unexpected problem on the server side:

• 500 Internal Server Error — An unhandled exception occurred. If you receive this consistently, check your request data and report the issue.

The 422 error body structure

When validation fails, the API returns a JSON object with a detail array. Each item in the array identifies the location of the problem (loc), a human-readable message (msg), and the error type (type):

{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}

The loc array tells you exactly where the invalid value appeared — body, path, or query — followed by the field name. Use this to pinpoint the issue without guessing.

The following examples demonstrate real error scenarios you are likely to encounter. Each shows the request, the HTTP status code returned, and the response body.

Example 1 — Missing required field in POST /orders

Omitting the required currency field triggers a 422 error.

curl -X POST http://localhost:8000/orders \
  -H "Content-Type: application/json" \
  -d '{"amount": 50}'

Expected response (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body", "currency"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Example 2 — Wrong type for amount in POST /orders

Passing a string where an integer is required also returns 422.

curl -X POST http://localhost:8000/orders \
  -H "Content-Type: application/json" \
  -d '{"amount": "fifty", "currency": "USD"}'

Expected response (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}

Example 3 — Non-integer path parameter in GET /orders/{order_id}

Path parameters must match their declared type. Passing a non-integer order_id returns 422.

curl http://localhost:8000/orders/abc

Expected response (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["path", "order_id"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}

Example 4 — Non-integer limit query parameter in GET /orders

Query parameters are also type-validated.

curl "http://localhost:8000/orders?limit=many"

Expected response (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}

Example 5 — Calling an unsupported method

Sending a PUT request to /orders returns 405 Method Not Allowed.

curl -X PUT http://localhost:8000/orders \
  -H "Content-Type: application/json" \
  -d '{"amount": 50, "currency": "USD"}'

Expected response (405 Method Not Allowed):

{
  "detail": "Method Not Allowed"
}

Use the table below to diagnose common error situations. Each entry follows the pattern: Symptom → Likely cause → Fix.

Symptom: You receive 422 Unprocessable Entity on POST /orders.

Likely cause: One or more required fields (amount, currency) are missing from the request body, have the wrong JSON type, or the Content-Type header is not set to application/json.

Fix: Check the detail array in the response body. Confirm loc points to the offending field. Ensure your request body is valid JSON and that Content-Type: application/json is included in your headers. Verify that amount is an integer and currency is a string.

Symptom: You receive 422 Unprocessable Entity when calling GET /orders/{order_id} or DELETE /orders/{order_id}.

Likely cause: The order_id in the URL path is not a valid integer (e.g., you passed a UUID string, a slug, or accidentally left a placeholder like {order_id}).

Fix: Ensure the order_id segment in the URL is a plain integer, for example /orders/42.

Symptom: You receive 422 Unprocessable Entity when calling GET /orders with a limit query parameter.

Likely cause: The limit value is not a valid integer. Common causes include passing a float (e.g., limit=10.5) or a string (e.g., limit=all).

Fix: Pass a whole number integer, for example ?limit=50.

Symptom: You receive 405 Method Not Allowed.

Likely cause: You used an HTTP method that the target endpoint does not support. For example, sending a PUT or PATCH to /orders, which only accepts GET and POST.

Fix: Refer to the API reference to confirm which methods each endpoint accepts. Use POST /orders to create an order, GET /orders to list, GET /orders/{order_id} to retrieve, and DELETE /orders/{order_id} to cancel.

Symptom: You receive 500 Internal Server Error.

Likely cause: An unexpected exception occurred on the server. This is not caused by client input validation and is not something you can fix by changing your request.

Fix: Check your server logs for a traceback. If the error is reproducible, note the exact request (endpoint, headers, body) and report it so the underlying bug can be investigated.

Symptom: The detail field in a 422 response contains multiple items.

Likely cause: More than one field in your request failed validation simultaneously.

Fix: Iterate over every item in the detail array and fix each reported field. The API validates all fields before returning and reports all failures at once, so a single corrected field may not be enough.