Errors

Wingspan uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a batch was already closed, etc.). Codes in the 5xx range indicate an error with Wingspan's servers (these are rare).

Some 4xx errors that could be handled programmatically include an error message that briefly explains the error reported.

Attributes

Attribute	Type	Description
code	integer	The HTTP status code of the response.
message	string	A human-readable message providing more details about the error.
errorMessage	string	For bulk batch item errors, found in `metadata.errorMessage` after batch processing completes.

HTTP Status Code Summary

Code	Name	Description
200	OK	Everything worked as expected.
208	Already Reported	The `bulkPayableItemReference` already exists. The existing item is returned to prevent duplicates.
400	Bad Request	The request was unacceptable, often due to missing a required parameter or invalid data format.
401	Unauthorized	No valid API key provided. Generate a new token in the Wingspan portal under Data & Integrations → Developer.
403	Forbidden	The API key doesn't have permissions to perform the request.
404	Not Found	The requested resource doesn't exist.
409	Conflict	The request conflicts with another request. We recommend an exponential backoff of your requests.
422	Unprocessable Entity	The request syntax was valid but the content cannot be processed.
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500	Server Error	Something went wrong on Wingspan's end. (These are rare.)

Error Types

Type	Description
Batch Error	Batch errors occur when attempting invalid operations on a bulk batch, such as invalid status transitions or modifying a closed batch.
Payable Item Error	Payable item errors occur when adding or updating items in a bulk payable batch with invalid or missing data.
Agent Item Error	Agent item errors occur when adding items to a bulk collaborator batch with invalid or conflicting data.

Common Error Messages

Batch Errors

Error Message	Code	Description
Status may only be updated from Open to Pending	400	Batches can only transition from Open to Pending.
Processing strategy cannot be updated once set	400	Create a new batch with your desired strategy instead.
Can only delete Empty or Incomplete batch	403	Only batches in Open status can be deleted.
Not found	404	The batch ID doesn't exist. Verify the `bulkCollaboratorBatchId` or `bulkPayableBatchId`.

Payable Item Errors

Error Message	Code	Description
BulkPayableBatch must be in status Open	400	Create a new batch to add additional items.
Bulk payable item batch must match request	400	The batch ID in the request body must match the URL.
Collaborator with externalId {value} does not exist	400	Create the Agent first or verify the `externalId`.
Amount must be set and a number	400	Provide a valid numeric amount.
LineItemDescription must be set and not empty	400	A description is required for each line item.
Failed to parse dueDate	400	Use YYYY-MM-DD format (e.g., 2025-12-15).
PayableStatus of {value} is not valid	400	Use: Draft, Open, Approved, Paid, or Cancelled.
Bulk payable item reference refers to item on payable in closed state	400	Payables can only be updated while in Draft or Open status.

Item Addition Errors

Error Message	Code	Description
BulkCollaboratorBatch must be in status Open	400	Create a new batch to add additional items.
Cannot set both engagementId and collaboratorGroupId	400	Use only one of these fields, not both.
Bulk collaborator batch not found	404	Verify the `bulkCollaboratorBatchId`.

Handling Errors

We recommend writing code that gracefully handles all possible API exceptions. Key practices include:

Log error responses — Capture full message bodies for debugging.
Use exponential backoff — Implement retry logic with jitter when handling 429 or 500 errors.
Validate before submission — Catch format issues (dates, amounts, required fields) before they reach the API.
Monitor batch completion — Check individual item statuses in metadata.errorMessage after a batch completes.

Rate Limits

Request Type	Limit
GET requests	200/second
POST, PATCH, DELETE	100/second

If you're regularly hitting limits, contact your Wingspan Solutions Engineer to discuss increasing them for your account.