Handle API Errors
Parse FreightCake API errors and decide when to correct, retry, or escalate a request.
FreightCake returns one JSON error envelope for every API-key endpoint.
Error Envelope
{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "Weight must be greater than zero",
"param": "items.0.weight",
"doc_url": "https://docs.freightcake.com/docs/errors"
}
}| Field | Type | Description |
|---|---|---|
type | string | Stable error category for programmatic handling |
code | string | Optional machine-readable reason |
message | string | Human-readable explanation |
param | string | Optional request field that failed validation |
doc_url | string | Optional link to relevant documentation |
HTTP Statuses
| Status | Type | Action |
|---|---|---|
400 | invalid_request_error | Correct the request before retrying |
401 | authentication_error | Replace or reactivate the API key |
403 | permission_error | Add the required key permission |
404 | invalid_request_error | Verify the resource ID and key mode |
409 | idempotency_error | Reuse the original payload or choose a new idempotency key |
422 | invalid_request_error | Correct a semantically invalid field or state transition |
429 | rate_limit_error | Wait for Retry-After, then retry with backoff |
500 | api_error | Retry an idempotent request with exponential backoff |
TypeScript
import { AuthenticationError, RateLimitError, ValidationError } from '@freightcake/sdk'
try {
await freightcake.quotes.create(input)
} catch (error) {
if (error instanceof ValidationError) {
console.error(error.param, error.message)
} else if (error instanceof RateLimitError) {
console.error('Retry after', error.retryAfter)
} else if (error instanceof AuthenticationError) {
console.error('Replace the API key')
} else {
throw error
}
}