Errors
The atoship API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.
HTTP Status Codes
Success Codes
Request succeeded
Resource created successfully
Client Errors
Invalid request parameters
Invalid or missing API key
Insufficient balance or payment failed
API key lacks required permissions
Resource does not exist
Validation error on request data
Rate limit exceeded
Server Errors
Something went wrong on our end
API is temporarily unavailable
Error Object
All errors return a JSON object with the following structure:
typestringError category (e.g., "invalid_request_error")
codestringMachine-readable error code
messagestringHuman-readable error description
paramstring (optional)Parameter that caused the error
request_idstringUnique request ID for debugging
Handling Errors
Use the status code to determine the error category
Read the error type and code for programmatic handling
Show the message to users for actionable feedback
Include request_id when contacting support
| 1 | { |
| 2 | "error": { |
| 3 | "type": "invalid_request_error", |
| 4 | "code": "invalid_parameter", |
| 5 | "message": "Invalid address: zip code is required", |
| 6 | "param": "to_address.zip", |
| 7 | "request_id": "req_abc123def456" |
| 8 | } |
| 9 | } |