Tài liệu API

Lỗi

Hãy xử lý theo mã máy, không theo câu chữ. Câu chữ là nhãn tiếng Anh cố định và có thể thay đổi.

Hai định dạng

Ở đâuĐịnh dạng
/v1/oauth/token, /revoke, /introspectRFC 6749 §5.2: { "error": "...", "error_description": "..." }. Xử lý theo error.
Mọi nơi khácRFC 7807 application/problem+json: type, title, status, detail, instance, correlation_id và code ổn định. Lỗi kiểm tra dữ liệu còn có errors: [{ field, code, message? }]. Xử lý theo code.
JSON
{
  "error": "invalid_grant",
  "error_description": "The grant is invalid, expired, revoked or was issued to another client"
}
JSON
{
  "type": "https://stracker.io/errors/idempotency-key-reused",
  "title": "Idempotency-Key reused with different payload",
  "status": 422,
  "detail": "Idempotency-Key reused with different payload",
  "instance": "/v1/trips",
  "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
  "code": "IDEMPOTENCY_KEY_REUSED"
}

Hãy nêu correlation_id khi liên hệ hỗ trợ: nó giúp chúng tôi tìm yêu cầu của bạn trong nhật ký.

Lỗi ở endpoint token

`error`HTTPÝ nghĩa và cách xử lý
invalid_request400Thiếu, lặp hoặc sai định dạng một tham số; gửi cả Basic lẫn assertion; client_id khác iss của assertion. Sửa yêu cầu.
invalid_client401Xác thực ứng dụng thất bại: ứng dụng không tồn tại hoặc bị tắt, khóa bí mật sai, bị thu hồi hoặc hết hạn, assertion sai. Cùng một câu trả lời cho tất cả. Kèm WWW-Authenticate: Basic realm="stracker".
invalid_grant400Code hoặc refresh token không hợp lệ, hết hạn, đã dùng, bị thu hồi hoặc cấp cho ứng dụng khác, hoặc PKCE verifier không khớp. Bắt đầu lại luồng.
unauthorized_client400Ứng dụng không được dùng loại cấp quyền này, hoặc (ứng dụng đối tác) chưa kết nối với tenant đó.
unsupported_grant_type400Dùng client_credentials, authorization_code hoặc refresh_token.
invalid_scope400Scope không tồn tại hoặc nằm ngoài những gì ứng dụng, lượt cài hay quyền đã cấp cho phép.
temporarily_unavailable503Hiện không khóa ký nào ký được, hoặc không ghi nhận được một lần thu hồi. Thử lại với độ trễ tăng dần.

Lỗi khi gọi API

`code`HTTPÝ nghĩa và cách xử lý
VALIDATION_FAILED400Nội dung hoặc query không hợp lệ; errors[] nêu từng trường. Sửa rồi gửi lại.
BAD_REQUEST400Yêu cầu sai định dạng hoặc không được phép ở trạng thái này.
AUTH_UNAUTHORIZED401Không có thông tin xác thực dùng được.
OAUTH_TOKEN_INVALID401Access token hết hạn, bị thu hồi hoặc sai định dạng. Lấy token mới (làm mới hoặc xin lại).
OAUTH_GRANT_REVOKED401Quyền đã cấp hoặc lượt cài phía sau token đã bị thu hồi. Nhờ người dùng hoặc đơn vị kết nối lại.
OAUTH_CLIENT_DISABLED401Ứng dụng của bạn bị tắt. Hãy liên hệ chúng tôi.
OAUTH_ROUTE_NOT_EXPOSED403Đường dẫn này không mở cho token OAuth. Xem tham chiếu.
OAUTH_INSUFFICIENT_SCOPE403Token thiếu scope. WWW-Authenticate nêu rõ scope đó. Nhờ đơn vị duyệt.
AUTH_FORBIDDEN403Scope đủ nhưng người dùng (token ủy quyền) hoặc vai trò của ứng dụng không được làm việc này trên bản ghi đó.
TENANT_SUSPENDED403Tài khoản của đơn vị đang bị đình chỉ.
EXTENSION_NOT_INSTALLED403Đơn vị chưa có tiện ích api.
NOT_FOUND, TRIP_NOT_FOUND404Bản ghi không tồn tại trong tenant này.
STALE_TRIP409expectedRev hoặc rev cũ hơn chuyến: không có gì được ghi. Đọc lại chuyến rồi quyết định.
TRIP_INVALID_STATE_TRANSITION409Trạng thái của chuyến không cho phép việc này (ví dụ dời lịch một chuyến đã bắt đầu).
RESOURCE_UNAVAILABLE409Tài xế hoặc phương tiện có thời gian không khả dụng đã duyệt trùng với chuyến.
IDEMPOTENCY_IN_PROGRESS409Cùng khóa vẫn đang được xử lý. Thử lại sau Retry-After.
IDEMPOTENCY_KEY_REUSED422Khóa đã dùng với nội dung khác. Dùng khóa mới.
RATE_LIMITED429Quá nhiều yêu cầu. Chờ Retry-After. Xem giới hạn tốc độ.
INTERNAL_ERROR500Lỗi phía chúng tôi. Thử lại với độ trễ tăng dần và cùng khóa idempotency; nêu correlation_id nếu còn lỗi.
WEBHOOK_URL_NOT_ALLOWED400URL webhook bị từ chối; params.reason nêu lý do.
WEBHOOK_EVENT_NOT_ALLOWED403Người gọi không được đăng ký một trong các loại sự kiện.
WEBHOOK_SUBSCRIPTION_LIMIT_REACHED409Đã đạt giới hạn subscription; hãy xóa bớt một cái.
WEBHOOK_SUBSCRIPTION_DISABLED409Subscription đang bị tắt: hãy bật lại trước.
WEBHOOK_SUBSCRIPTION_NOT_EDITABLE409Người gọi này không được đổi subscription đó: người dùng của đơn vị không thể sửa hay đổi khóa bí mật của subscription thuộc ứng dụng.
WEBHOOK_MESSAGE_EXPIRED410Thông điệp quá cũ để gửi lại.
Mọi mã lỗi của API công khai (55)

Các mã dưới đây là những mã một tích hợp có thể gặp. Tiêu đề là nhãn tiếng Anh cố định; hãy xử lý theo mã, không theo câu chữ.

MãÝ nghĩa
AUTH_FORBIDDENForbidden
AUTH_UNAUTHORIZEDUnauthorized
BAD_REQUESTBad request
DRIVER_PERSON_NOT_FOUNDDriver not found for this person id
EXTENSION_NOT_INSTALLEDExtension not installed
IDEMPOTENCY_IN_PROGRESSThis request is still being processed. Try again in a moment
IDEMPOTENCY_KEY_REUSEDIdempotency-Key reused with different payload
INTERNAL_ERRORInternal server error
NOT_FOUNDResource not found
OAUTH_APP_ALREADY_INSTALLEDApp is already installed
OAUTH_APP_NOT_INSTALLEDApp is not installed in this workspace
OAUTH_CLIENT_AUTH_METHOD_MISMATCHOauth client auth method mismatch
OAUTH_CLIENT_DISABLEDOAuth client is disabled
OAUTH_CLIENT_KEY_DUPLICATEOauth client key duplicate
OAUTH_CLIENT_KEY_INVALIDOauth client key invalid
OAUTH_CLIENT_KEY_LIMIT_REACHEDOauth client key limit reached
OAUTH_CLIENT_SECRET_LIMIT_REACHEDOAuth client secret limit reached
OAUTH_CONNECTION_APPROVAL_WIDENSApproval asks for more than the request
OAUTH_CONNECTION_LINK_EXPIREDConnection request link has expired
OAUTH_CONNECTION_LINK_INVALIDConnection request link is not valid
OAUTH_CONNECTION_REQUEST_CLOSEDConnection request is closed
OAUTH_CONSENT_NOT_ALLOWEDConsent not allowed
OAUTH_GRANT_REVOKEDAccess grant was revoked
OAUTH_GRANT_TYPE_NOT_ALLOWEDGrant type not allowed for this client
OAUTH_HANDOFF_ALREADY_VIEWEDCredentials were already shown
OAUTH_HANDOFF_CODE_INVALIDVerification code is not valid
OAUTH_HANDOFF_CODE_LIMITVerification code limit reached
OAUTH_HANDOFF_EXPIREDCredential link has expired
OAUTH_HANDOFF_LINK_INVALIDCredential link is not valid
OAUTH_HANDOFF_LOCKEDCredential link is locked
OAUTH_INSTALL_REQUEST_CLOSEDInstall request is closed
OAUTH_INSUFFICIENT_SCOPEAccess token scope is insufficient
OAUTH_REAUTH_REQUIREDRecent sign-in required
OAUTH_REDIRECT_URI_MISMATCHRedirect URI does not match
OAUTH_REDIRECT_URI_NOT_ALLOWEDRedirect URI not allowed
OAUTH_ROUTE_NOT_EXPOSEDThis route is not available to API access tokens
OAUTH_SCOPE_NOT_ALLOWEDScope is not allowed
OAUTH_SIGNING_KEY_NOT_REVOCABLESigning key cannot be revoked
OAUTH_TENANT_REQUIREDA tenant is required
OAUTH_TOKEN_INVALIDAccess token is invalid
OAUTH_WORKSPACE_CHANGEDWorkspace changed
RATE_LIMITEDToo many requests
RESOURCE_UNAVAILABLEResource unavailable
STALE_TRIPStale trip
TENANT_SUSPENDEDTenant account suspended — contact your administrator
TRIP_INVALID_STATE_TRANSITIONTrip invalid state transition
TRIP_NOT_FOUNDTrip not found
VALIDATION_FAILEDValidation failed
WEBHOOK_EVENT_NOT_ALLOWEDWebhook event not allowed
WEBHOOK_MESSAGE_EXPIREDWebhook message expired
WEBHOOK_SIGNATURE_INVALIDWebhook signature invalid
WEBHOOK_SUBSCRIPTION_DISABLEDWebhook subscription disabled
WEBHOOK_SUBSCRIPTION_LIMIT_REACHEDWebhook subscription limit reached
WEBHOOK_SUBSCRIPTION_NOT_EDITABLEWebhook subscription not editable
WEBHOOK_URL_NOT_ALLOWEDWebhook url not allowed

Mỗi thao tác trong tham chiếu liệt kê các trạng thái nó có thể trả và nguyên nhân.