Errors
Your SimplifyTrip API integration may need to handle errors at runtime. These errors generally fall into these categories:
-
Content errors happen when request payload is invalid. They return HTTP 4xx responses. Example:
401for invalid API key, or400for missing required parameter. -
Network errors happen when communication between client and server is interrupted. They usually appear as low-level errors such as socket exceptions or timeouts. A network error does not always mean the request failed at server side.
-
Server errors happen when issues occur on SimplifyTrip servers. They return HTTP 5xx responses. These are rare, but integrations must still handle them safely.
The right handling strategy depends on the error type.
HTTP Status Code
SimplifyTrip uses standard HTTP response codes to indicate API request success and failure:
2xx: success4xx: client-side/request errors5xx: server-side errors
HTTP status codes for successful requests
| HTTP Status | Meaning |
|---|---|
| 200 | OK - Request processed successfully. Default status for most GET requests. |
| 201 | Created - Resource created successfully. Default status for most POST requests. |
| 204 | No Content - Resource deleted successfully. Default status for most DELETE requests. |
HTTP status codes for failed requests
| HTTP Status | Meaning |
|---|---|
| 400 | Bad Request - Invalid request payload or request format. |
| 401 | Unauthorized - API key missing, expired, or invalid. |
| 403 | Forbidden - API key does not have permission for this resource. |
| 404 | Not Found - Requested resource does not exist or has been deleted. |
| 405 | Method Not Allowed - HTTP method is not supported by this endpoint. |
| 422 | Unprocessable Entity - Request data is semantically invalid. |
| 429 | Too Many Requests - Request rate exceeded the limit. |
| 500 | Internal Server Error - Unexpected server-side issue. |
| 503 | Service Unavailable - Service is temporarily unavailable (maintenance or outage). |
Error codes
| Error Code | Meaning |
|---|---|
| TOO_MANY_REQUESTS | Rate limit exceeded. |
| BAD_REQUEST | Invalid request parameters. |
| UNAUTHORIZED | API key is missing or invalid, request cannot be authenticated. |
| FORBIDDEN | API key does not have permission to perform this request. |
| INTERNAL_SERVER_ERROR | Unexpected internal API error (rare). |
Error Handling
Safely retry requests with idempotency
Idempotency means an operation can be applied multiple times with the same result as the first successful attempt. This is critical when network interruptions happen and request status is uncertain.
SimplifyTrip guarantees idempotency for GET requests. For POST/PATCH, use an Idempotency key to avoid duplicate operations. Example: if create order times out, retrying with the same Idempotency key prevents duplicate orders.
Idempotency key is sent in request headers. Common strategies:
- Generate a random token such as
UUID v4 - Derive key from user-owned object IDs (for example cart ID)
Content errors
Content errors are 4xx errors caused by invalid request payload. Fix the payload and retry.
For POST with Idempotency key: once request execution starts, SimplifyTrip can store the result for that key, including 4xx responses. If you change the payload, create a new Idempotency key.
Network errors
Network errors are connection-level failures such as socket or timeout exceptions.
When network interruptions occur, retry with the same Idempotency key and same parameters until a definitive server response is received. Reusing the same key with different parameters causes a mismatch error.
Server errors
Server errors are 5xx responses. They are the hardest to handle and should be considered non-deterministic.
Retrying with the same Idempotency key often returns a similar result. Retrying with a new key may create side effects, so it is usually not recommended unless you fully understand the request behavior.