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}