Hai định dạng
| Ở đâu | Định dạng |
|---|---|
/v1/oauth/token, /revoke, /introspect | RFC 6749 §5.2: { "error": "...", "error_description": "..." }. Xử lý theo error. |
| Mọi nơi khác | RFC 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. |
{
"error": "invalid_grant",
"error_description": "The grant is invalid, expired, revoked or was issued to another client"
}{
"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_request | 400 | Thiế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_client | 401 | Xá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_grant | 400 | Code 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_client | 400 | Ứ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_type | 400 | Dùng client_credentials, authorization_code hoặc refresh_token. |
invalid_scope | 400 | Scope 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_unavailable | 503 | Hiệ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_FAILED | 400 | Nộ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_REQUEST | 400 | Yêu cầu sai định dạng hoặc không được phép ở trạng thái này. |
AUTH_UNAUTHORIZED | 401 | Không có thông tin xác thực dùng được. |
OAUTH_TOKEN_INVALID | 401 | Access 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_REVOKED | 401 | Quyề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_DISABLED | 401 | Ứng dụng của bạn bị tắt. Hãy liên hệ chúng tôi. |
OAUTH_ROUTE_NOT_EXPOSED | 403 | Đường dẫn này không mở cho token OAuth. Xem tham chiếu. |
OAUTH_INSUFFICIENT_SCOPE | 403 | Token thiếu scope. WWW-Authenticate nêu rõ scope đó. Nhờ đơn vị duyệt. |
AUTH_FORBIDDEN | 403 | Scope đủ 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_SUSPENDED | 403 | Tài khoản của đơn vị đang bị đình chỉ. |
EXTENSION_NOT_INSTALLED | 403 | Đơn vị chưa có tiện ích api. |
NOT_FOUND, TRIP_NOT_FOUND | 404 | Bản ghi không tồn tại trong tenant này. |
STALE_TRIP | 409 | expectedRev 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_TRANSITION | 409 | Trạ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_UNAVAILABLE | 409 | Tà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_PROGRESS | 409 | Cùng khóa vẫn đang được xử lý. Thử lại sau Retry-After. |
IDEMPOTENCY_KEY_REUSED | 422 | Khóa đã dùng với nội dung khác. Dùng khóa mới. |
RATE_LIMITED | 429 | Quá nhiều yêu cầu. Chờ Retry-After. Xem giới hạn tốc độ. |
INTERNAL_ERROR | 500 | Lỗ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_ALLOWED | 400 | URL webhook bị từ chối; params.reason nêu lý do. |
WEBHOOK_EVENT_NOT_ALLOWED | 403 | Người gọi không được đăng ký một trong các loại sự kiện. |
WEBHOOK_SUBSCRIPTION_LIMIT_REACHED | 409 | Đã đạt giới hạn subscription; hãy xóa bớt một cái. |
WEBHOOK_SUBSCRIPTION_DISABLED | 409 | Subscription đang bị tắt: hãy bật lại trước. |
WEBHOOK_SUBSCRIPTION_NOT_EDITABLE | 409 | Ngườ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_EXPIRED | 410 | Thô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_FORBIDDEN | Forbidden |
AUTH_UNAUTHORIZED | Unauthorized |
BAD_REQUEST | Bad request |
DRIVER_PERSON_NOT_FOUND | Driver not found for this person id |
EXTENSION_NOT_INSTALLED | Extension not installed |
IDEMPOTENCY_IN_PROGRESS | This request is still being processed. Try again in a moment |
IDEMPOTENCY_KEY_REUSED | Idempotency-Key reused with different payload |
INTERNAL_ERROR | Internal server error |
NOT_FOUND | Resource not found |
OAUTH_APP_ALREADY_INSTALLED | App is already installed |
OAUTH_APP_NOT_INSTALLED | App is not installed in this workspace |
OAUTH_CLIENT_AUTH_METHOD_MISMATCH | Oauth client auth method mismatch |
OAUTH_CLIENT_DISABLED | OAuth client is disabled |
OAUTH_CLIENT_KEY_DUPLICATE | Oauth client key duplicate |
OAUTH_CLIENT_KEY_INVALID | Oauth client key invalid |
OAUTH_CLIENT_KEY_LIMIT_REACHED | Oauth client key limit reached |
OAUTH_CLIENT_SECRET_LIMIT_REACHED | OAuth client secret limit reached |
OAUTH_CONNECTION_APPROVAL_WIDENS | Approval asks for more than the request |
OAUTH_CONNECTION_LINK_EXPIRED | Connection request link has expired |
OAUTH_CONNECTION_LINK_INVALID | Connection request link is not valid |
OAUTH_CONNECTION_REQUEST_CLOSED | Connection request is closed |
OAUTH_CONSENT_NOT_ALLOWED | Consent not allowed |
OAUTH_GRANT_REVOKED | Access grant was revoked |
OAUTH_GRANT_TYPE_NOT_ALLOWED | Grant type not allowed for this client |
OAUTH_HANDOFF_ALREADY_VIEWED | Credentials were already shown |
OAUTH_HANDOFF_CODE_INVALID | Verification code is not valid |
OAUTH_HANDOFF_CODE_LIMIT | Verification code limit reached |
OAUTH_HANDOFF_EXPIRED | Credential link has expired |
OAUTH_HANDOFF_LINK_INVALID | Credential link is not valid |
OAUTH_HANDOFF_LOCKED | Credential link is locked |
OAUTH_INSTALL_REQUEST_CLOSED | Install request is closed |
OAUTH_INSUFFICIENT_SCOPE | Access token scope is insufficient |
OAUTH_REAUTH_REQUIRED | Recent sign-in required |
OAUTH_REDIRECT_URI_MISMATCH | Redirect URI does not match |
OAUTH_REDIRECT_URI_NOT_ALLOWED | Redirect URI not allowed |
OAUTH_ROUTE_NOT_EXPOSED | This route is not available to API access tokens |
OAUTH_SCOPE_NOT_ALLOWED | Scope is not allowed |
OAUTH_SIGNING_KEY_NOT_REVOCABLE | Signing key cannot be revoked |
OAUTH_TENANT_REQUIRED | A tenant is required |
OAUTH_TOKEN_INVALID | Access token is invalid |
OAUTH_WORKSPACE_CHANGED | Workspace changed |
RATE_LIMITED | Too many requests |
RESOURCE_UNAVAILABLE | Resource unavailable |
STALE_TRIP | Stale trip |
TENANT_SUSPENDED | Tenant account suspended — contact your administrator |
TRIP_INVALID_STATE_TRANSITION | Trip invalid state transition |
TRIP_NOT_FOUND | Trip not found |
VALIDATION_FAILED | Validation failed |
WEBHOOK_EVENT_NOT_ALLOWED | Webhook event not allowed |
WEBHOOK_MESSAGE_EXPIRED | Webhook message expired |
WEBHOOK_SIGNATURE_INVALID | Webhook signature invalid |
WEBHOOK_SUBSCRIPTION_DISABLED | Webhook subscription disabled |
WEBHOOK_SUBSCRIPTION_LIMIT_REACHED | Webhook subscription limit reached |
WEBHOOK_SUBSCRIPTION_NOT_EDITABLE | Webhook subscription not editable |
WEBHOOK_URL_NOT_ALLOWED | Webhook 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.