Error Codes

Comprehensive guide to error responses and troubleshooting for the Partner API v2.

Error Response Format

All API errors follow the RFC 7807 Problem Details specification, providing consistent, structured error information.

Standard Response Fields:

• type - URI identifying the specific error type with detailed documentation link
• status - HTTP status code as integer
• title - Brief, human-readable error summary
• detail - Specific explanation of the error instance
• errors - Validation error array (for 400 Bad Request responses)

Common Error Types

Errors are organized by HTTP status code:

Client Errors (4xx)

Status Code	Error Type	Description
400	Bad Request	Invalid parameters, malformed data, or validation failures
401	Unauthorized	Missing, invalid, or expired authentication credentials
403	Forbidden	Valid authentication but insufficient permissions
404	Not Found	Requested resource does not exist or is not accessible

Server Errors (5xx)

Status Code	Error Type	Description
500	Internal Server Error	Unexpected server-side errors requiring support attention

Error Handling Best Practices

Implement robust error handling using these guidelines:

1. Check Status Codes - Use the status field to determine error category and appropriate response
2. Handle Specific Errors - Use the type field for programmatic error identification and handling
3. User-Friendly Messages - Display the detail field for context-specific error information
4. Validation Errors - Parse the errors array to highlight specific field validation issues
5. Retry Logic - Implement appropriate retry strategies based on error type:
   • Retry: 500 Internal Server Error (with exponential backoff)
   • Don't Retry: 401 Unauthorized, 403 Forbidden, 404 Not Found

Example Error Response

{
  "type": "https://partner.utopi.io/docs/help/./error-codes/400#validation-error",
  "status": 400,
  "title": "Bad Request",
  "detail": "The request contains validation errors in the following fields.",
  "errors": [
    {
      "property": "startDate",
      "message": "Start date must be in ISO 8601 format (YYYY-MM-DD)"
    },
    {
      "property": "spaceUuid",
      "message": "SpaceUuid must be a valid GUID"
    }
  ]
}

Troubleshooting Steps

For any error encountered:

1. Review the specific error code page for detailed resolution steps
2. Check API documentation for correct endpoint usage and parameter formats
3. Verify authentication and permissions for the requested resource
4. Contact your technical contact for persistent issues or questions

Support

Each error code page includes specific troubleshooting guidance. For additional assistance:

• Technical Issues: Contact your technical contact
• General Support: support@utopi.co.uk
• Include in requests: Full error response and example request for faster resolution