Error Handling

This guide covers error responses, common error codes, and troubleshooting strategies for the Consignly API.

Error Response Format

When an API request fails, Consignly returns an error response with an appropriate HTTP status code and error details in the response body.

Error Response Schema:

{
  "ErrorType": "string",
  "ErrorMessages": ["string", "string"],
}

Example Error Response:

{
  "ErrorType": "Validation Failed",
  "ErrorMessages": [
    "Client code is required.",
    "Expected dispatch date must be in the future."
  ]
}

HTTP Status Codes

The Consignly API uses standard HTTP status codes to indicate the success or failure of requests.

Success Codes

Client Error Codes

Rate Limiting

The Consignly API enforces rate limits to ensure fair usage and platform stability. Rate limits are applied on a sliding window basis at different scopes.

Rate Limit Thresholds

Rate Limit Response

When exceeding the rate limit, the API returns a 429 Too Many Requests response:

{
  "ErrorType": "RateLimitExceeded",
  "ErrorMessages": ["Connection has exceeded the request quota. Please try again after XYZ second(s)."]
}

Handling Rate Limits

When rate limited (429 Too Many Requests):

1. Check the Retry-After header for recommended wait time (if provided)
2. Implement exponential backoff
3. Consider caching frequently accessed data to reduce API calls
4. Batch requests where possible (e.g., use consignment import instead of individual creates)
5. Spread requests over time rather than bursting

Common Errors and Solutions

Authentication Errors

401 Unauthorized

Cause: Missing, expired, or invalid access token.

Solutions:

1. Ensure the Authorization header is included: Authorization: Bearer ACCESS_TOKEN
2. Check if the token has expired and refresh if necessary
3. Verify the token was obtained with correct credentials

403 Forbidden

Cause: The authenticated user lacks permission for the requested operation.

Solutions:

1. Verify the app has the required scopes
2. Confirm the user has appropriate permissions in Consignly
3. Check if the resource belongs to the organization

Validation Errors

400 Bad Request

Cause: Invalid request format, missing required fields, or invalid parameter values.

Solutions:

1. Check that all required fields are included
2. Verify data types match the expected format
3. Ensure dates use ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
4. Confirm UUIDs are properly formatted

Resource Errors

404 Not Found

Cause: The requested resource does not exist or is not accessible.

Solutions:

1. Verify the resource ID is correct
2. Confirm the resource exists in the organization
3. Check for typos in the endpoint path

The Consignment Check Exists Response Codes

The GET /v1/consignments/{consignmentId}/check-exists endpoint can be used to resolve if a consignment exists or is a pending import:

Idempotency Errors

409 Conflict

Cause: A request with the same idempotency key has already been processed.

Solutions:

1. Use a unique idempotency key for each new request
2. If retrying a failed request, use the same idempotency key
3. Check if the original request was successful

Getting Help

If encountering persistent errors:

1. Check this documentation for known solutions
2. Review the Consignly Help Center
3. Contact support at https://www.consignlyhq.com/contact

When contacting support, include:

• The API endpoint and HTTP method
• Request headers (excluding sensitive data)
• Request body
• Response status code and body
• Timestamp of the request