Errors

Errors happen—the PostCo API is designed to make them easy to understand and fix. All error responses include standard HTTP status codes, human-readable messages, and specific error codes you can programmatically handle. Below you'll find common errors and recommended solutions.

The PostCo API uses conventional HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error caused by the request (e.g., invalid parameters, authentication failure), and codes in the 5xx range indicate an error with PostCo's servers (rare).

HTTP status codes

Name
200 OK
Description
The request succeeded. The response body contains the requested data.
Name
400 Bad Request
Description
The request was malformed or contains invalid parameters. Check the error message for details about which parameter is invalid.
Name
401 Unauthorized
Description
Authentication failed or was not provided. Verify your API key is correct and properly formatted in the Authorization header.
Name
404 Not Found
Description
The requested resource doesn't exist or doesn't belong to your shop. Verify the ID and ensure you have access to this resource.
Name
429 Too Many Requests
Description
You've exceeded the rate limit. Implement exponential backoff and retry after a delay.
Name
500 Internal Server Error
Description
An error occurred on PostCo's servers. These are rare. If the issue persists, contact support.

Error response format

When an error occurs, the API returns a structured JSON response with detailed error information. This format enables programmatic error handling while providing clear debugging information.

Error responses always include:

HTTP status code: Indicates the category of error (2xx = success, 4xx = client error, 5xx = server error)
error.type: The error category (e.g., validation_error, authentication_error)
error.code: A machine-readable error code for programmatic handling
error.message: A human-readable description of the problem
error.param (optional): The specific parameter that caused the error

You can use the code field to implement specific error handling logic in your application, while displaying the message to help with debugging.

Error response example

{
  "error": {
    "type": "validation_error",
    "code": "invalid_date_format",
    "message": "Invalid submitted_at_min format. Expected ISO8601 datetime.",
    "param": "submitted_at_min"
  }
}

Example error request

curl -G https://360.postco.co/api/public/v1/return_orders \
  -H "Authorization: Bearer sk_invalid_key" \
  -d submitted_at_min="invalid-date"

# HTTP/1.1 400 Bad Request
# {
#   "error": {
#     "type": "validation_error",
#     "code": "invalid_date_format",
#     "message": "Invalid submitted_at_min format. Expected ISO8601 datetime.",
#     "param": "submitted_at_min"
#   }
# }

Error types

The API uses six error types to categorize all possible errors:

Name
authentication_error
Description
HTTP 401: Issues with API authentication. Check your API key is valid, not revoked, and properly formatted in the Authorization header.
Name
validation_error
Description
HTTP 400: Invalid request parameters. The error will specify which parameter is invalid and why. Fix the parameter value and retry.
Name
resource_error
Description
HTTP 404: The requested resource doesn't exist or doesn't belong to your shop. Verify the resource ID and your access permissions.
Name
state_error
Description
HTTP 422: The requested operation isn't allowed in the resource's current state. For example, trying to receive a return order that's already completed.
Name
rate_limit_error
Description
HTTP 429: You've exceeded the rate limit. Implement exponential backoff and retry after a delay. See Rate Limits for details.
Name
api_error
Description
HTTP 500: An error occurred on PostCo's servers. These are rare. If the issue persists, contact support.

Error code reference

All errors include a machine-readable code field for programmatic handling. Here are all possible error codes:

Error Code	Type	HTTP	Description	Applies To
`missing_api_key`	`authentication_error`	401	The `Authorization` header is missing or doesn't contain a Bearer token. Include `Authorization: Bearer sk_your_api_key_here` in every request header.	—
`invalid_api_key`	`authentication_error`	401	The API key is incorrect, malformed, or has been revoked. Verify the key starts with `sk_`, is 67 characters long, and hasn't been revoked in the dashboard.	—
`invalid_date_format`	`validation_error`	400	Date parameters aren't in ISO8601 format. Use ISO8601 format: `2025-10-01T00:00:00Z`	`submitted_at_min`, `submitted_at_max`
`invalid_date_range`	`validation_error`	400	The minimum date is greater than the maximum date. Ensure `submitted_at_min` is less than or equal to `submitted_at_max`.	`submitted_at_min`, `submitted_at_max`
`invalid_status_value`	`validation_error`	400	The status filter contains invalid values. Only use valid return order statuses: `pending`, `reviewed`, `received`, `resolving`, `pending_payment_from_customer`, `stripe_account_disabled`, `pending_action`, `completing`, `handle_manually`, `completed`, `rejected`, or `archived`.	`statuses`
`invalid_statuses_format`	`validation_error`	400	The `statuses` parameter contains empty values in the comma-separated list. Ensure no empty values: `statuses=pending,reviewed`	`statuses`
`invalid_ids_format`	`validation_error`	400	The `ids` parameter contains non-numeric values or is malformed. Provide comma-separated numeric IDs: `ids=123,456,789`	`ids`
`invalid_order_names_format`	`validation_error`	400	The `order_names` parameter contains empty values in the comma-separated list. Ensure no empty values: `order_names=ORDER-001,ORDER-002`	`order_names`
`invalid_cursor_format`	`validation_error`	400	The cursor parameter is invalid or malformed. Cursors are opaque pagination tokens—do not modify, decode, or manually construct them. Always use the exact `next_cursor` value returned from a previous API response.	`cursor`
`missing_items_array`	`validation_error`	400	Request body must contain an "items" array when reviewing return orders.	`items`
`missing_items`	`validation_error`	400	Not all pending items are included in the request. All pending refunds and exchanges must be reviewed in a single request.	`items`
`invalid_action`	`validation_error`	400	Action must be one of: "approve", "reject", or "keep_item".	`items[].action`
`invalid_item_type`	`validation_error`	400	Type must be either "refund" or "exchange".	`items[].type`
`item_not_found`	`validation_error`	400	One or more item IDs don't match pending items in the return order.	`items[].id`
`keep_item_not_allowed`	`validation_error`	400	The shop does not have the keep_item feature enabled. Only shops with this feature can use action="keep_item".	`items[].action`
`missing_reject_reason`	`validation_error`	400	reject_reason is required when action is "reject". Provide a reason for rejecting the item.	`items[].reject_reason`
`return_order_not_found`	`resource_error`	404	The return order doesn't exist, belongs to a different shop, or is in draft/cancelled status. Verify the ID is correct and that the return order has been submitted.	—
`invalid_state_transition`	`state_error`	422	The requested operation isn't allowed for the return order's current status. Each operation requires a specific status: `pending` for review, `reviewed` for receive. Check the current status and verify the return order is ready for this operation.	—
`rate_limit_exceeded`	`rate_limit_error`	429	You've made too many requests in a short period. Implement exponential backoff. Wait progressively longer between retries (1s, 2s, 4s, 8s, etc.). For detailed information about rate limits, see the Rate Limits page.	—

Error handling best practices

Name
Implement retry logic
Description
For 429 and 5xx errors, implement exponential backoff with jitter. Don't retry 4xx errors (except 429) as they indicate client-side problems.
Name
Log error responses
Description
Log the full error response including status code and message for debugging. This helps identify patterns in failures.
Name
Handle errors gracefully
Description
Display user-friendly messages to end users while logging technical details for developers. Don't expose API keys or sensitive data in error messages.
Name
Monitor error rates
Description
Track your error rates to identify integration issues early. A sudden spike in 400 errors might indicate a code deployment issue.
Name
Validate before sending
Description
Validate parameters client-side before making API requests to reduce unnecessary 400 errors. This improves performance and user experience.