square_rust/api/models/objects/error.rs
1//! Models for errors returned by the Connect API.
2
3use serde::{Deserialize, Serialize};
4
5/// Represents an error encountered during a request to the Connect API.
6#[derive(Debug, Serialize, Deserialize, Clone)]
7pub struct SquareError {
8 /// The high-level category for the error.
9 pub category: ErrorCategory,
10 /// The specific code of the error.
11 pub code: ErrorCode,
12 /// A human-readable description of the error for debugging purposes.
13 pub detail: Option<String>,
14 /// The name of the field provided in the original request (if any) that the error pertains to.
15 pub fileld: Option<String>,
16}
17
18/// The high-level category for the error.
19#[derive(Debug, Serialize, Deserialize, Clone)]
20#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
21pub enum ErrorCategory {
22 /// An error occured with the Connect API itself.
23 ApiError,
24 /// An authentication error occured. Most commonly, the request had a missing, malformed, or otherwise invalid Authorization header.
25 AuthenticationError,
26 /// The request was invalid. Most commonly, a required parameter was missing, or a provided parameter had an invalid value.
27 InvalidRequestError,
28 /// Your application reached the Square API rate limit. You might receive this error if your application sends a high number of requests to Square APIs in a short period of time.
29 /// Your application should monitor responses for 429 RATE_LIMITED errors and use a retry mechanism with an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) schedule to resend the requests at an increasingly slower rate. It is also a good practice to use a randomized delay (jitter) in your retry schedule.
30 RateLimitError,
31 /// An error occurred while processing a payment method. Most commonly, the details of the payment method were invalid (such as a card's CVV or expiration date).
32 PaymentMethodError,
33 /// An error occurred while attempting to process a refund.
34 RefundError,
35 /// An error occurred when checking a merchant subscription status
36 MerchantSubscriptionError, // BETA
37 /// An error that is returned from an external vendor's API
38 ExternalVendorError,
39}
40
41/// The specific code of the error.
42#[derive(Debug, Serialize, Deserialize, Clone)]
43#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
44pub enum ErrorCode {
45 /// A general server error occurred.
46 InternalServerError,
47 /// A general authorization error occurred.
48 UnAuthorized,
49 /// The provided access token has expired.
50 AccessTokenExpired,
51 /// The provided access token has been revoked.
52 AccessTokenRevoked,
53 /// The provided client has been disabled.
54 ClientDisabled,
55 /// A general access error occurred.
56 ForBidden,
57 /// The provided access token does not have permission to execute the requested action.
58 InsufficientScope,
59 /// The calling application was disabled.
60 ApplicationDisabled,
61 /// The calling application was created prior to 2016-03-30 and is not compatible with v2 Square API calls.
62 V1Application,
63 /// The calling application is using an access token created prior to 2016-03-30 and is not compatible with v2 Square API calls.
64 V1AccessToken,
65 /// The location provided in the API call is not enabled for credit card processing.
66 CardProcessingNotEnabled,
67 /// A required subscription was not found for the merchant
68 MerchantSubscriptionNotFound, // BETA
69 /// A general error occurred with the request.
70 BadRequest,
71 /// The request is missing a required path, query, or body parameter.
72 MissingRequiredParameter,
73 /// The value provided in the request is the wrong type. For example, a string instead of an integer.
74 IncorrectType,
75 /// Formatting for the provided time value is incorrect.
76 InvalidTime,
77 /// The time range provided in the request is invalid. For example, the end time is before the start time.
78 InvalidTimeRange,
79 /// The provided value is invalid. For example, including % in a phone number.
80 InvalidValue,
81 /// The pagination cursor included in the request is invalid.
82 InvalidCursor,
83 /// The query parameters provided is invalid for the requested endpoint.
84 UnknownQueryParameter,
85 /// One or more of the request parameters conflict with each other.
86 ConflictingParameters,
87 /// The request body is not a JSON object.
88 ExpectedJSONBody,
89 /// The provided sort order is not a valid key. Currently, sort order must be ASC or DESC.
90 InvalidSortOrder,
91 /// The provided value does not match an expected regular expression.
92 ValueRegexMismatch,
93 /// The provided string value is shorter than the minimum length allowed.
94 ValueTooShort,
95 /// The provided string value is longer than the maximum length allowed.
96 ValueTooLong,
97 /// The provided value is less than the supported minimum.
98 ValueTooLow,
99 /// The provided value is greater than the supported maximum.
100 ValueTooHigh,
101 /// The provided value has a default (empty) value such as a blank string.
102 ValueEmpty,
103 /// The provided array has too many elements.
104 ArrayLengthTooLong,
105 /// The provided array has too few elements.
106 ArrayLengthTooShort,
107 /// The provided array is empty.
108 ArrayEmpty,
109 /// The endpoint expected the provided value to be a boolean.
110 ExpectedBoolean,
111 /// The endpoint expected the provided value to be an integer.
112 ExpectedInteger,
113 /// The endpoint expected the provided value to be a float.
114 ExpectedFloat,
115 /// The endpoint expected the provided value to be a string.
116 ExpectedString,
117 /// The endpoint expected the provided value to be a JSON object.
118 ExpectedObject,
119 /// The endpoint expected the provided value to be an array or list.
120 ExpectedArray,
121 /// The endpoint expected the provided value to be a map or associative array.
122 ExpectedMap,
123 /// The endpoint expected the provided value to be an array encoded in base64.
124 ExpectedBase64EncodedByteArray,
125 /// One or more objects in the array does not match the array type.
126 InvalidArrayValue,
127 /// The provided static string is not valid for the field.
128 InvalidEnumValue,
129 /// Invalid content type header.
130 InvalidContentType,
131 /// Only relevant for applications created prior to 2016-03-30. Indicates there was an error while parsing form values.
132 InvalidFormValue,
133 /// The provided customer id can't be found in the merchant's customers list.
134 CustomerNotFound,
135 /// A general error occurred.
136 OneInstrumentExpected,
137 /// A general error occurred.
138 NoFieldsSet,
139 /// Too many entries in the map field.
140 TooManyMapEntries,
141 /// The length of one of the provided keys in the map is too short.
142 MapKeyLengthTooShort,
143 /// The length of one of the provided keys in the map is too long.
144 MapKeyLengthTooLong,
145 /// The provided customer does not have a recorded name.
146 CustomerMissingName,
147 /// The provided customer does not have a recorded email.
148 CustomerMissingEmail,
149 /// The subscription cannot be paused longer than the duration of the current phase.
150 InvalidPauseLenghth,
151 /// The subscription cannot be paused/resumed on the given date.
152 InvalidDate,
153 /// The API request references an unsupported country.
154 UnsupportedCountry,
155 /// The API request references an unsupported currency.
156 UnsupportedCurrency,
157 /// The payment was declined by the card issuer during an Apple Tap to Pay (TTP) transaction with a request for the card's PIN. This code will be returned alongside CARD_DECLINED_VERIFICATION_REQUIRED as a supplemental error, and will include an issuer-provided token in the details field that is needed to initiate the PIN collection flow on the iOS device.
158 AppleTipPinToken,
159 /// The card issuer declined the request because the card is expired.
160 CardExpired,
161 /// The expiration date for the payment card is invalid. For example, it indicates a date in the past.
162 InvalidExpiration,
163 /// The expiration year for the payment card is invalid. For example, it indicates a year in the past or contains invalid characters.
164 InvalidExpirationYear,
165 /// The expiration date for the payment card is invalid. For example, it contains invalid characters.
166 InvalidExpirationDate,
167 /// The credit card provided is not from a supported issuer.
168 UnsupportedCardBrand,
169 /// The entry method for the credit card (swipe, dip, tap) is not supported.
170 UnsupportedEntryMethod,
171 /// The encrypted card information is invalid.
172 InvalidEncryptedCard,
173 /// The credit card cannot be validated based on the provided details.
174 InvalidCard,
175 /// The payment was declined because there was a payment amount mismatch. The money amount Square was expecting does not match the amount provided.
176 PaymentAmountMismatch,
177 /// Square received a decline without any additional information. If the payment information seems correct, the buyer can contact their issuer to ask for more information.
178 GenericDecline,
179 /// The card issuer declined the request because the CVV value is invalid.
180 CvvFailure,
181 /// The card issuer declined the request because the postal code is invalid.
182 AddressVerificationFailure,
183 /// The issuer was not able to locate the account on record.
184 InvalidAccount,
185 /// The currency associated with the payment is not valid for the provided funding source. For example, a gift card funded in USD cannot be used to process payments in GBP.
186 CurrencyMismatch,
187 /// The funding source has insufficient funds to cover the payment.
188 InsufficientFunds,
189 /// The Square account does not have the permissions to accept this payment. For example, Square may limit which merchants are allowed to receive gift card payments.
190 InsufficientPermissions,
191 /// The card issuer has declined the transaction due to restrictions on where the card can be used. For example, a gift card is limited to a single merchant.
192 CardholderInsufficientPermissions,
193 /// The Square account cannot take payments in the specified region. A Square account can take payments only from the region where the account was created.
194 InvalidLocation,
195 /// The card issuer has determined the payment amount is either too high or too low. The API returns the error code mostly for credit cards (for example, the card reached the credit limit). However, sometimes the issuer bank can indicate the error for debit or prepaid cards (for example, card has insufficient funds).
196 TransactionLimit,
197 /// The card issuer declined the request because the issuer requires voice authorization from the cardholder. The seller should ask the customer to contact the card issuing bank to authorize the payment.
198 VoiceFailure,
199 /// The specified card number is invalid. For example, it is of incorrect length or is incorrectly formatted.
200 PanFailure,
201 /// The card issuer declined the request because the PIN is invalid.
202 ExpirationFailure,
203 /// The card is not supported either in the geographic region or by the [merchant category code](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) (MCC).
204 CardNotSupported,
205 /// The card issuer declined the request because the PIN is invalid.
206 InvalidPin,
207 /// The payment is missing a required PIN.
208 MissingPin,
209 /// The payment is missing a required ACCOUNT_TYPE parameter.
210 MissingAccountType,
211 /// The postal code is incorrectly formatted.
212 InvalidPostalCode,
213 /// The app_fee_money on a payment is too high.
214 InvalidFees,
215 /// The card must be swiped, tapped, or dipped. Payments attempted by manually entering the card number are declined.
216 ManuallyEnteredPaymentNotSupported,
217 /// Square declined the request because the payment amount exceeded the processing limit for this merchant.
218 PaymentLimitExceeded,
219 /// When a Gift Card is a payment source, you can allow taking a partial payment by adding the accept_partial_authorization parameter in the request. However, taking such a partial payment does not work if your request also includes tip_money, app_fee_money, or both. Square declines such payments and returns the GIFT_CARD_AVAILABLE_AMOUNT error. For more information, see [CreatePayment errors (additional information).](https://developer.squareup.com/docs/payments-api/error-codes#createpayment-errors-additional-information)
220 GiftCardAvailableAmount,
221 /// The account provided cannot carry out transactions.
222 AccountUnusable,
223 /// Bank account rejected or was not authorized for the payment.
224 BuyerRefusedPayment,
225 /// The application tried to update a delayed-capture payment that has expired.
226 DelayedTransactionExpired,
227 /// The application tried to cancel a delayed-capture payment that was already cancelled.
228 DelayedTransactionCanceled,
229 /// The application tried to capture a delayed-capture payment that was already captured.
230 DelayedTransactionCaptured,
231 /// The application tried to update a delayed-capture payment that failed.
232 DelayedTransactionFailed,
233 /// The provided card token (nonce) has expired.
234 CardTokenExpired,
235 /// The provided card token (nonce) was already used to process the payment or refund.
236 CardTokenUsed,
237 /// The requested payment amount is too high for the provided payment source.
238 AmountTooHigh,
239 /// The API request references an unsupported instrument type.
240 UnsupportedInstrumentType,
241 /// The requested refund amount exceeds the amount available to refund.
242 RefundAmountInvalid,
243 /// The payment already has a pending refund.
244 RefundAlreadyPending,
245 /// The payment is not refundable. For example, the payment has been disputed and is no longer eligible for refunds.
246 PaymentNotRefundable,
247 /// Request failed - The card issuer declined the refund.
248 RefundDeclined,
249 /// The Square account does not have the permissions to process this refund.
250 InsufficientPermissionsForRefund,
251 /// Generic error - the provided card data is invalid.
252 InvalidCardData,
253 /// The provided source id was already used to create a card.
254 SourceUsed,
255 /// The provided source id has expired.
256 SourceExpired,
257 /// The referenced loyalty program reward ties is not supported. This cloud happen if the reward tier created in a first party application is incompatible with the Loyalty API.
258 UnsupportedLoyaltyRewardTier,
259 /// Generic error - the given location does not matching what is expected.
260 LocationMismatch,
261 /// The provided idempotency key has already been used.
262 IdempotencyKeyReused,
263 /// General error - the value provided was unexpected.
264 UnexpectedValue,
265 /// The API request is not supported in sandbox.
266 SandboxNotSupported,
267 /// The provided email address is invalid.
268 InvalidEmailAddress,
269 /// The provided phone number is invalid.
270 InvalidPhoneNumber,
271 /// The provided checkout URL has expired.
272 CheckoutExpired,
273 /// Bad certificate.
274 BadCertificate,
275 /// The provided Square-Version is incorrectly formatted.
276 InvalidSquareVersionFormat,
277 /// The provided Square-Version is incompatible with the requested action.
278 ApiVersionIncompatible,
279 /// The transaction requires that a card be present.
280 CardPresenceRequired,
281 /// The API request references an unsupported source type.
282 UnsupportedSourceType,
283 /// The provided card does not match what is expected.
284 CardMismatch,
285 /// Generic plaid error
286 PlaidError,
287 /// Plaid error - ITEM_LOGIN_REQUIRED
288 PlaidErrorItemLoginRequired,
289 /// Plaid error - RATE_LIMIT
290 PlaidErrorRateLimit,
291 /// The card was declined.
292 CardDeclined,
293 /// The CVV could not be verified.
294 VerifyCvvFailure,
295 /// The AVS could not be verified.
296 VerifyAvsFailure,
297 /// The payment card was declined with a request for the card holder to call the issuer.
298 CardDeclinedCallIssuer,
299 /// The payment card was declined with a request for additional verification.
300 CardDeclinedVerificationRequired,
301 /// The card expiration date is either missing or incorrectly formatted.
302 BadExpiration,
303 /// The card issuer requires that the card be read using a chip reader.
304 ChipInsertionRequired,
305 /// The card has exhausted its available pin entry retries set by the card issuer. Resolving the error typically requires the card holder to contact the card issuer.
306 AllowablePinTriesExceeded,
307 /// The card issuer declined the refund.
308 ReservationDeclined,
309 /// The body parameter is not recognized by the requested endpoint.
310 UnknownBodyParameter,
311 /// Not Found - a general error occurred.
312 NotFound,
313 /// Square could not find the associated Apple Pay certificate.
314 ApplePaymentProcessingCertificateHashNotFound,
315 /// Method Not Allowed - a general error occurred.
316 MethodNotAllowed,
317 /// Not Acceptable - a general error occurred.
318 NotAcceptable,
319 /// Request Timeout - a general error occurred.
320 RequestTimeout,
321 /// Conflict - a general error occurred.
322 Conflict,
323 /// The target resource is no longer available and this condition is likely to be permanent.
324 Gone,
325 /// Request Entity Too Large - a general error occurred.
326 RequestEntityTooLarge,
327 /// Unsupported Media Type - a general error occurred.
328 UnsupportedMediaType,
329 /// Unprocessable Entity - a general error occurred.
330 UnprocessableEntity,
331 /// Rate Limited - a general error occurred.
332 RateLimited,
333 /// Not Implemented - a general error occurred.
334 NotImplemented,
335 /// Bad Gateway - a general error occurred.
336 BadGateway,
337 /// Service Unavailable - a general error occurred.
338 ServiceUnavailable,
339 /// A temporary internal error occurred. You can safely retry your call using the same idempotency key.
340 TemporaryError,
341 /// Gateway Timeout - a general error occurred.
342 GatewayTimeout,
343}